共用方式為

自動載入器選項

特定於 cloudFiles 來源的組態選項以 cloudFiles 為首碼，因此它們位於與其他結構化串流來源選項不同的命名空間中。

常見自動載入器選項

您可以為自動載入器資料流設定下列選項。

選項
cloudFiles.allowOverwrites
類型:Boolean
是否允許輸入目錄檔案變更以覆寫現有的資料。
如需設定注意事項，請參閱自動載入器是否會在檔案附加或覆寫時再次處理檔案？
預設：false
cloudFiles.backfillInterval
類型:Interval String
自動載入器可以觸發指定間隔的異步回填。 例如 1 day ，每日回填或 1 week 每周回填。 如需詳細資訊，請參閱 使用 cloudFiles.backfillInterval 觸發一般回填。
當cloudFiles.useManagedFileEvents設定為true時，請勿使用。
默認值：無
cloudFiles.cleanSource
類型:String
是否要從輸入目錄自動刪除已處理的檔案。 當設定為 OFF [預設值] 時，不會刪除任何檔案。
當設定為 DELETE時，自動載入器會在處理檔案 30 天后自動刪除檔案。 若要這樣做，自動載入器必須具有來源目錄的寫入許可權。
當設定為 MOVE時，自動載入器會在處理檔案後 30 天內自動將檔案移至指定的位置 cloudFiles.cleanSource.moveDestination 。 若要這樣做，自動載入器必須具有來源目錄以及移動位置的寫入許可權。
當檔案在數據表值函式的結果commit_time中有非 Null 值cloud_files_state時，會將其視為已處理。 請參閱 cloud_files_state 資料表值函式。 處理完成後的額外等待 30 天可以透過 cloudFiles.cleanSource.retentionDuration 來設定。
注意：如果來源位置有多個數據流取用數據，Databricks 不建議使用此選項，因為最快的取用者會刪除檔案，而且它們不會內嵌在較慢的來源中。
注意：啟用此功能需要自動載入器在其檢查點中維護額外的狀態，這會產生效能額外負荷，但可透過 cloud_files_state 數據表值函式改善可檢視性。 請參閱 cloud_files_state 資料表值函式。
注意：cleanSource會使用目前的設定來決定是否要對給定的檔案進行MOVE或DELETE。 例如，假設在檔案原本處理時設定是 MOVE，但在30天後檔案變成清除候選專案時，設定變更為 DELETE。 在此情況下，cleanSource 將會刪除檔案。
注意： cleanSource 盡力而為。 不保證 文件會 在期限結束後 retentionDuration 立即被刪除。 相反地，它們會成為清除的候選者，並在一般串流處理期間以最大努力的方式刪除。 為了節省成本，cleanSource 在串流處理完成後將優雅結束，即使還有候選仍待清除。 其餘候選人將在下一次處理時被接走。
適用於 Databricks Runtime 16.4 和更新版本。
預設值：OFF
cloudFiles.cleanSource.retentionDuration
類型:Interval String
處理後的文件成為封存候選對象前需要等待的時間量，使用 cleanSource。 必須大於 7 天對於 DELETE。 沒有最低限制 MOVE.
適用於 Databricks Runtime 16.4 和更新版本。
默認值：30 天
cloudFiles.cleanSource.moveDestination
類型:String
當 cloudFiles.cleanSource 設定為 MOVE 時，歸檔已處理檔案的路徑。
移動位置受到以下限制：
  • 不應該是來源目錄的子目錄（這會導致封存檔案被重新匯入）
  • S3：應該是相同 S3 儲存桶中的目錄。 跨儲存桶移動需要下載並重新上傳至新的儲存桶，這可能很昂貴。
  • GCS：應該是相同 GCS 儲存區中的目錄。 跨儲存桶移動需要下載並重新上傳至新的儲存桶，這可能很昂貴。
  • Azure：應該是相同 Azure 容器中的目錄。 跨容器移動需要下載檔案並重新上傳至新的容器，這很昂貴。

自動載入器必須具有此目錄的寫入許可權。
適用於 Databricks Runtime 16.4 和更新版本。
預設值：無
cloudFiles.format
類型:String
來源路徑中的數據 檔案格式 。 允許的值包括：

預設值：無（必要選項）
cloudFiles.includeExistingFiles
類型:Boolean
是包含串流處理輸入路徑中的現有檔案，還是僅處理初始設定後到達的新檔案。 僅在您第一次啟動串流時會評估此選項。 在重新啟動串流後變更此選項沒有任何作用。
預設：true
cloudFiles.inferColumnTypes
類型:Boolean
在使用結構描述進行推斷時，是否要推斷精確的資料行類型。 根據預設，在推斷 JSON 和 CSV 資料集時，資料行會推斷為字串。 如需詳細資訊 ，請參閱架構推斷 。
預設：false
cloudFiles.maxBytesPerTrigger
類型:Byte String
每個觸發程序中要處理的新位元組數目上限。 您可以指定位元組字串 (例如 10g)，將每個微批次限制為 10 GB 資料。 這是軟性上限。 如果每個檔案為 3 GB，則 Azure Databricks 在一個微批次中可以處理 12 GB。 與 cloudFiles.maxFilesPerTrigger 一起使用時，Azure Databricks 將最多消耗到 cloudFiles.maxFilesPerTrigger 或 cloudFiles.maxBytesPerTrigger 的下限，視哪一項先達到而定。 與 Trigger.Once() (Trigger.Once() 已取代) 一起使用時，此選項沒有任何作用。
默認值：無
cloudFiles.maxFileAge
類型:Interval String
為去重目的而追蹤檔案事件的時間長度。 Databricks 不建議調整此參數，除非您正在以每小時數百萬個檔案的速度匯入資料。 如需詳細資訊，請參閱 檔案事件追蹤 一節。
過於激進地調整 cloudFiles.maxFileAge 可能會導致資料品質問題，例如重複擷取或遺漏檔案。 因此，Databricks 建議為 cloudFiles.maxFileAge 使用保守設定，例如 90 天，這與類似資料擷取解決方案建議的值相當。
默認值：無
cloudFiles.maxFilesPerTrigger
類型:Integer
每個觸發程序中要處理的新檔案數目上限。 與 cloudFiles.maxBytesPerTrigger 一起使用時，Azure Databricks 將最多消耗到 cloudFiles.maxFilesPerTrigger 或 cloudFiles.maxBytesPerTrigger 的下限，視哪一項先達到而定。 與 Trigger.Once() (已取代) 一起使用時，此選項沒有任何作用。
預設值：1000
cloudFiles.partitionColumns
類型:String
要從檔案的目錄結構推斷的以逗號分隔的 Hive 樣式分割欄位清單。 Hive 樣式分割欄位是由等號結合的鍵值對，例如 <base-path>/a=x/b=1/c=y/file.format。 在此範例中，分割欄位為 a、b 和 c。 如果您使用架構推斷並提供 <base-path> 載入資料的來源，則這些數據行預設會自動新增至您的架構。 如果您提供結構描述，自動載入器會預期這些資料行包含在結構描述中。 如果不希望這些資料行成為結構描述的一部分，您可以指定 "" 以略過這些資料行。 此外，當您希望將資料行推斷為複雜目錄結構中的檔案路徑時，可以使用此選項，如下列範例所示：
<base-path>/year=2022/week=1/file1.csv
<base-path>/year=2022/month=2/day=3/file2.csv
<base-path>/year=2022/month=2/day=4/file3.csv
指定 cloudFiles.partitionColumns 為 year,month,day 為 year=2022 返回 file1.csv，但 month 和 day 欄位為 null。
month 和 day 已正確剖析針對 file2.csv 和 file3.csv。
默認值：無
cloudFiles.schemaEvolutionMode
類型:String
探索資料時發現新資料行後的結構演進方式。 根據預設，在推斷 JSON 資料集時，資料行會推斷為字串。 如需詳細資訊，請參閱 架構演進 。
預設值： addNewColumns 未提供架構時， none 否則為
cloudFiles.schemaHints
類型:String
您在結構描述推斷期間提供給自動載入器的結構描述資訊。 如需詳細資訊 ，請參閱架構提示 。
默認值：無
cloudFiles.schemaLocation
類型:String
儲存推斷結構描述和後續變更的位置。 如需詳細資訊 ，請參閱架構推斷 。
預設值：無（推斷架構所需）
cloudFiles.useStrictGlobber
類型:Boolean
是否使用與 Apache Spark 中其他檔案來源的預設萬用字元匹配行為相符的嚴格萬用字元規則？ 如需詳細資訊 ，請參閱常見數據載入模式 。 在 Databricks Runtime 12.2 LTS 和更新版本中可用。
預設：false
cloudFiles.validateOptions
類型:Boolean
是否要驗證 Auto Loader 的選項，並對未知或不一致的選項返回錯誤。
預設：true

目錄清單選項

下列選項與目錄清單模式相關。

選項
cloudFiles.useIncrementalListing (已取代)
類型:String
這個功能已被取代。 Databricks 建議使用 搭配檔案事件的檔案通知模式 ，而不是使用 cloudFiles.useIncrementalListing。
是否在目錄清單模式下使用累加式清單，而不是完整列表。 根據預設，自動載入器竭盡所能自動偵測指定目錄是否適用於累加式清單。 您可以明確使用累加式清單，或者透過將完整目錄清單分別設定為 true 或 false 來使用該清單。
不正確地在非依詞彙排序的目錄上啟用累加式清單會阻止自動載入器探索新檔案。
使用 Azure Data Lake Storage （abfss://）、S3 （s3://） 和 GCS （gs://）。
可用於 Databricks Runtime 9.1 LTS 和更新版本。
預設值： auto 在 Databricks Runtime 17.2 和更新版本上， false 在 Databricks Runtime 17.3 和更新版本上
可用值：auto、true、false

檔案通知選項

下列選項與檔案通知模式相關。

選項
cloudFiles.fetchParallelism
類型:Integer
從佇列服務擷取訊息時要使用的執行緒數目。
當cloudFiles.useManagedFileEvents設定為true時，請勿使用。
預設值：1
cloudFiles.pathRewrites
類型：JSON 字串
僅在您指定從多個 S3 儲存桶接收文件通知的 queueUrl，並欲利用為存取這些容器中的資料而設定的掛載點時，才需要此選項。 使用此選項可使用掛載點重新寫入 bucket/key 路徑的前綴。 只能重寫前綴。 例如，針對組態 {"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}，路徑 s3://<databricks-mounted-bucket>/path/2017/08/fileA.json 會重寫為 dbfs:/mnt/data-warehouse/2017/08/fileA.json。
當cloudFiles.useManagedFileEvents設定為true時，請勿使用。
默認值：無
cloudFiles.resourceTag
類型:Map(String, String)
一系列索引鍵/值標籤組，可協助關聯和識別相關資源，例如：
cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue")
.option("cloudFiles.resourceTag.mySecondKey", "mySecondValue")
如需 AWS 的詳細資訊，請參閱 Amazon SQS 成本配置標籤 和 設定 Amazon SNS 標籤主題。 (1)
如需 Azure 的詳細資訊，請參閱命名佇列和元資料，以及properties.labels中的涵蓋範圍。 自動載入器將這些索引鍵/值標籤組以 JSON 格式儲存為標籤。 (1)
如需 GCP 的詳細資訊，請參閱 使用標籤報告使用量。 (1)
當cloudFiles.useManagedFileEvents設定為true時，請勿使用。 請改用雲端提供者控制台來設定資源標籤。
默認值：無
cloudFiles.useManagedFileEvents
當設定為 true時，自動載入器會使用檔案事件服務來探索外部位置中的檔案。 只有在載入路徑位於已啟用檔案事件的外部位置時，才可以使用此選項。 請參閱 檔案事件搭配檔案通知模式的使用方法。
檔案事件會在檔案探索中提供通知層級的效能，因為自動載入器可以在上次執行後探索新的檔案。 不同於目錄清單，此程式不需要列出目錄中的所有檔案。
有些情況下，即使已啟用檔案事件選項，自動載入器仍會使用目錄清單：
  • 在初始載入期間的自動載入器，當includeExistingFiles設定為true時，會進行完整目錄列舉，以探索自動載入器啟動之前存在於目錄中的所有檔案。
  • 檔案事件服務會快取最近建立的檔案，以優化檔案探索。 如果自動載入器不常執行，此快取可能會過期，而自動載入器會回復到目錄清單，以探索檔案並更新快取。 若要避免這種情況，請至少每隔七天叫用自動載入器一次。

請參閱具有 檔案事件的自動載入器何時使用目錄清單？ ，以取得自動載入器使用此選項使用目錄清單時的完整清單。
支援 Databricks Runtime 14.3 LTS 及以上版本。
cloudFiles.useNotifications
類型:Boolean
是否使用檔案通知模式來確定何時存在新檔案。 如果為 false，則使用目錄清單模式。 請參閱 比較自動載入器檔案偵測模式。
當cloudFiles.useManagedFileEvents設定為true時，請勿使用。
預設：false

（1） 自動載入器預設會以最佳方式新增下列索引鍵/值標記組：

  • vendor：Databricks
  • path：從中載入資料的位置。 由於標籤限制，在 GCP 中不可用。
  • checkpointLocation：資料流檢查點的位置。 由於標籤限制，在 GCP 中不可用。
  • streamId：串流的全域唯一識別碼。

這些索引鍵名稱是保留的，無法覆寫其值。

檔案格式選項

使用自動載入器，您可以擷取 JSON、CSV、PARQUET、AVRO、TEXT、BINARYFILE 和 ORC 檔案。

泛型選項

下列選項適用於所有檔案格式。

選項
ignoreCorruptFiles
類型:Boolean
是否要略過損毀的檔案。 如果為 true，則 Spark 作業會在遇到損毀的檔案時繼續執行，而且仍然會傳回已讀取的內容。 可觀測到，如 numSkippedCorruptFiles 中所示
Delta Lake 歷程記錄的 operationMetrics 欄位。 在 Databricks Runtime 11.3 LTS 和更新版本中可用。
預設值：false
ignoreMissingFiles
類型:Boolean
是否略過遺漏的檔案。 如果為 true，則 Spark 作業會在遇到遺漏的檔案時繼續執行，而且仍然會傳回已讀取的內容。 在 Databricks Runtime 11.3 LTS 和更新版本中可用。
預設值：false 用於自動載入器，true 用於 COPY INTO（舊版）
modifiedAfter
類型：Timestamp String，例如 2021-01-01 00:00:00.000000 UTC+0
使用可選擇的時間戳作為篩選條件，只處理在提供的時間戳之後具有修改時間戳的檔案。
預設值：無
modifiedBefore
類型：Timestamp String，例如 2021-01-01 00:00:00.000000 UTC+0
選用一個時間戳作為篩選條件，只匯入修改時間戳在提供的時間戳之前的檔案。
預設值：無
pathGlobFilter 或 fileNamePattern
類型:String
潛在的 Glob 模式，用於選擇檔案。 相當於
PATTERN 中的 COPY INTO（舊版）。 fileNamePattern 可以在 read_files 中使用。
預設值：無
recursiveFileLookup
類型:Boolean
此選項會搜尋巢狀目錄，即使其名稱未遵循數據分割命名配置，例如 date=2019-07-01。
預設值：false

JSON 選項

選項
allowBackslashEscapingAnyCharacter
類型:Boolean
是否允許反斜線逸出其後面的任何字元。 如果未啟用，則只能逸出 JSON 規格明確列出的字元。
預設值：false
allowComments
類型:Boolean
是否允許在剖析的內容中使用 Java、C 和 C++ 樣式註解 ('/'、'*' 和 '//' 變體)。
預設值：false
allowNonNumericNumbers
類型:Boolean
是否允許將非數 (NaN) 符號集合用作合法浮點數值。
預設值：true
allowNumericLeadingZeros
類型:Boolean
是否允許整數以附加的 (可略過的) 零開頭 (例如 000001)。
預設值：false
allowSingleQuotes
類型:Boolean
是否允許使用單引號 (撇號字元 '\') 來引用字串 (名稱和字串值)。
預設值：true
allowUnquotedControlChars
類型:Boolean
是否允許 JSON 字串包含未經轉義的控制字元（ASCII 值小於 32 的字元，包括定位字元和換行字元）。
預設值：false
allowUnquotedFieldNames
類型:Boolean
是否允許使用未加上引號的欄位名稱 (JavaScript 允許，但 JSON 規格不允許)。
預設值：false
badRecordsPath
類型:String
用於記錄有關錯誤 JSON 記錄的資訊的檔案儲存路徑。
在檔案型資料來源中使用 badRecordsPath 選項具有以下限制：
  • 這是非交易式，可能會導致結果不一致。
  • 暫時性錯誤會被視為失敗。

預設值：無
columnNameOfCorruptRecord
類型:String
儲存格式錯誤且無法解析的記錄的資料行。 如果用於剖析的 mode 設定為 DROPMALFORMED，則此資料行將為空。
預設值：_corrupt_record
dateFormat
類型:String
用於剖析日期字串的格式。
預設值：yyyy-MM-dd
dropFieldIfAllNull
類型:Boolean
是否要在結構推斷期間忽略所有值為 Null 的欄、空陣列和空結構。
預設值：false
encoding 或 charset
類型:String
JSON 檔案編碼的名稱。 如需選項清單，請參閱 java.nio.charset.Charset。 當 UTF-16 為 UTF-32 時，您無法使用 multiline 和 true。
預設值：UTF-8
inferTimestamp
類型:Boolean
是否嘗試將時間戳記字串推斷為 TimestampType。 設定為
true 時，模式推斷的時間可能顯著延長。 您必須啟用 cloudFiles.inferColumnTypes，才能與自動載入器搭配使用。
預設值：false
lineSep
類型:String
兩筆連續 JSON 記錄之間的字串。
預設值：無，其中涵蓋 \r、\r\n 和 \n
locale
類型:String
java.util.Locale 識別碼。 影響 JSON 中的預設日期、時間戳記和小數解析。
預設值：US
mode
類型:String
用於處理格式錯誤記錄的解析器模式。 PERMISSIVE、DROPMALFORMED 或 FAILFAST 的其中之一。
預設值：PERMISSIVE
multiLine
類型:Boolean
JSON 記錄是否跨越多行。
預設值：false
prefersDecimal
類型:Boolean
如果可能，嘗試將字串類型推斷成 DecimalType 而非浮點型或雙精度型。 還必須透過啟用以下項來使用結構描述推斷：
inferSchema 或將 cloudFiles.inferColumnTypes 與自動載入器搭配使用。
預設值：false
primitivesAsString
類型:Boolean
是否將數字和布林值等基本類型推斷為 StringType。
預設值：false
readerCaseSensitive
類型:Boolean
指定啟用 rescuedDataColumn 時的大小寫敏感行為。 如果為 true，則修復名稱因大小寫不同而與架構不匹配的資料行；否則，請不區分大小寫地讀取資料。 可在 Databricks Runtime 中使用
13.3 及以上。
預設值：true
rescuedDataColumn
類型:String
是否將因資料類型不匹配或架構不匹配（包括欄位大小寫）而無法解析的所有資料收集到另一個資料行。 使用自動載入器時，系統會預設包含這個欄位。 如需詳細資訊，請參閱 什麼是救援資料欄位？。
COPY INTO （舊版） 不支援已獲救的數據行，因為您無法使用 COPY INTO手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
預設值：無
singleVariantColumn
類型:String
是否擷取整個 JSON 文件，將其剖析為以指定字串作為資料行名稱的單一 Variant 資料行。 如果停用，JSON 欄位將會匯入至個別的資料行。
預設值：無
timestampFormat
類型:String
用於剖析時間戳記字串的格式。
預設值：yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
類型:String
在剖析時間戳記和日期時使用的 java.time.ZoneId。
預設值：無

CSV 選項

選項
badRecordsPath
類型:String
用於記錄有關錯誤 CSV 記錄的資訊的檔案儲存路徑。
預設值：無
charToEscapeQuoteEscaping
類型:Char
用來對用於逸出引號的字元進行逸出的字元。 例如，對於下列記錄：[ " a\\", b ]：
  • 如果用來逃脫 '\' 的字元未定義，則不會解析記錄。 剖析器會將字元讀取為 [a],[\],["],[,],[ ],[b]，並拋出錯誤，因為找不到結束引號。
  • 如果將逸出字元定義為 '\'，則該記錄會以兩個值來讀取，即 '\' 和 [a\]。

預設值：'\0'
columnNameOfCorruptRecord
支援自動加載功能。 不支援 COPY INTO（舊版）。
類型:String
儲存格式錯誤且無法解析的記錄的資料行。 如果用於剖析的 mode 設定為 DROPMALFORMED，則此資料行將為空。
預設值：_corrupt_record
comment
類型:Char
定義表示行註解的字元 (位於文字行的開頭時)。 使用 '\0' 來停用註解略過功能。
預設值：'\u0000'
dateFormat
類型:String
用於剖析日期字串的格式。
預設值：yyyy-MM-dd
emptyValue
類型:String
空值的字串表示法。
預設值：""
encoding 或 charset
類型:String
CSV 檔案編碼的名稱。 如需選項清單，請參閱 java.nio.charset.Charset。 當 UTF-16 為 UTF-32 時，不能使用 multiline 和 true。
預設值：UTF-8
enforceSchema
類型:Boolean
是否將指定的或推斷的結構描述強制套用於 CSV 檔案。 如果啟用此選項，則會略過 CSV 檔案的標頭。 根據預設，當使用自動載入器來修復資料並允許結構描述演進時，會略過此選項。
預設值：true
escape
類型:Char
剖析資料時要使用的跳脫字元。
預設值：'\'
header
類型:Boolean
CSV 檔案是否包含標頭。 自動載入器在推斷結構描述時，假設檔案具有標頭。
預設值：false
ignoreLeadingWhiteSpace
類型:Boolean
是否忽略每個解析值的前置空白字元。
預設值：false
ignoreTrailingWhiteSpace
類型:Boolean
是否略過每個解析值的尾部空白字元。
預設值：false
inferSchema
類型:Boolean
是推斷所剖析 CSV 記錄的資料類型，還是假設所有資料行都是 StringType。 如果設定為 true，則需要對資料進行另一輪作業。 針對自動載入器，請改用 cloudFiles.inferColumnTypes。
預設值：false
lineSep
類型:String
兩筆連續 CSV 記錄之間的字串。
預設值：無，其中涵蓋 \r、\r\n 和 \n
locale
類型:String
java.util.Locale 識別碼。 影響 CSV 內的預設日期、時間戳記和十進位解析。
預設值：US
maxCharsPerColumn
類型:Int
要解析的值的最大可容納字元數。 可用於避免記憶體錯誤。 預設為 -1，這表示無限制。
預設值：-1
maxColumns
類型:Int
記錄可以包含的資料行數的硬性限制。
預設值：20480
mergeSchema
類型:Boolean
是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。 自動載入器在推斷結構時，預設是啟用的。
預設值：false
mode
類型:String
用於處理格式錯誤記錄的解析器模式。 下列其中一項：'PERMISSIVE'
'DROPMALFORMED' 和 'FAILFAST'。
預設值：PERMISSIVE
multiLine
類型:Boolean
CSV 記錄是否跨多行。
預設值：false
nanValue
類型:String
在剖析 FloatType 和 DoubleType 欄位時，表示非數字值的字串。
預設值："NaN"
negativeInf
類型:String
當解析 FloatType 或 DoubleType 欄時，負無限大的字串表示法。
預設值："-Inf"
nullValue
類型:String
空值的字串表示法。
預設值：""
parserCaseSensitive (已取代)
類型:Boolean
讀取檔案時，是否以區分大小寫的方式將標頭中宣告的欄位與結構描述對應起來。 對於自動載入器，此選項預設為 true。 如果啟用，則會在 rescuedDataColumn 中復原大小寫有差異的資料行。 此選項已取代為 readerCaseSensitive。
預設值：false
positiveInf
類型:String
解析 FloatType 或 DoubleType 欄位時，正無限大的字串表示法。
預設值："Inf"
preferDate
類型:Boolean
如果可能，嘗試將字串推斷為日期而不是時間戳記。 你必須啟用 inferSchema 或使用結構推斷來完成此操作。
cloudFiles.inferColumnTypes 搭配自動載入器使用。
預設值：true
quote
類型:Char
當欄位分隔符號是值的一部分時用於逸出值的字元。
預設值："
readerCaseSensitive
類型:Boolean
指定啟用 rescuedDataColumn 時的大小寫敏感行為。 如果為 true，則修復名稱因大小寫不同而與架構不匹配的資料行；否則，請不區分大小寫地讀取資料。
預設值：true
rescuedDataColumn
類型:String
是否要收集因下列原因而無法剖析的所有數據：數據類型不匹配，以及結構不匹配（包括欄位大小寫）到個別的欄位。 使用自動載入器時，系統會預設包含這個欄位。 如需詳細資訊，請參閱 什麼是修復的數據欄？。
COPY INTO （舊版） 不支援已獲救的數據行，因為您無法使用 COPY INTO手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
預設值：無
sep 或 delimiter
類型:String
欄位之間的分隔符號字串。
預設值：","
skipRows
類型:Int
CSV 檔案開頭應略過的資料列數 (包括註解資料列和空資料列)。 如果 header 為 true，則標頭將是第一個未略過且未註解的列。
預設值：0
timestampFormat
類型:String
用於剖析時間戳記字串的格式。
預設值：yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
類型:String
在剖析時間戳記和日期時使用的 java.time.ZoneId。
預設值：無
unescapedQuoteHandling
類型:String
處理未逸出引號的策略。 允許的選項：
  • STOP_AT_CLOSING_QUOTE：如果在輸入中發現未經處理的引號，則會記錄引號字元，並繼續將值解析為帶引號的值，直至找到右引號。
  • BACK_TO_DELIMITER：如果在輸入中發現了未轉義的引號，則視該值為未加引號的值。 這會使剖析器累積目前剖析值的所有字元，直到找到 sep 定義的分隔符號。 如果在值中找不到分隔符號，剖析器會繼續從輸入累積字元，直至找到分隔符號或行尾結束符號為止。
  • STOP_AT_DELIMITER：如果在輸入中發現了未轉義的引號，則視該值為未加引號的值。 這會使剖析器累積所有字元，直至在輸入中找到 sep 定義的分隔符號或找到行尾結束符號。
  • SKIP_VALUE：如果在輸入中發現未處理的引號，則從該值開始的內容會被略過（直到找到下一個分隔符為止），然後將產生 nullValue 中設定的值。
  • RAISE_ERROR：如果在輸入中找到未轉義的引號，則為
    TextParsingException將被拋出。

預設值：STOP_AT_DELIMITER

XML 選項

選項 描述 Scope
rowTag 要將 XML 檔案中的行標籤視為資料列。 在範例 XML <books> <book><book>...<books> 中，適當的值為 book。 這是必要選項。 讀取
samplingRatio 定義用於推斷資料模式的資料列分數比例。 XML 內建函數會略過此選項。 預設值：1.0。 讀取
excludeAttribute 是否要排除元素中的屬性。 預設值：false。 讀取
mode 在剖析過程中處理損壞資料記錄的模式。
PERMISSIVE：對於損毀的記錄，將格式錯誤的字串放入由 columnNameOfCorruptRecord 設定的欄位中，並將格式錯誤的欄位設定為 null。 若要保留損毀的記錄，您可以在使用者定義的結構描述中設定名為 string 的 columnNameOfCorruptRecord 類型欄位。 如果結構中沒有該欄位，在剖析過程中會忽略損毀的記錄。 推斷結構描述時，剖析器會隱含地在輸出結構描述中新增 columnNameOfCorruptRecord 欄位。
DROPMALFORMED：略過損毀的記錄。 XML 內建函數不支援此模式。
FAILFAST：在剖析器遇到損毀的記錄時拋出異常。		 讀取
inferSchema 如果為 true，則嘗試推斷每個產生的 DataFrame 資料行的適當類型。 如果為 false，則所有產生的資料行都是 string 類型。 預設：
true。 XML 內建函數會略過此選項。		 讀取
columnNameOfCorruptRecord 允許重新命名包含格式不正確字串的新欄位
PERMISSIVE 模式。 預設值：spark.sql.columnNameOfCorruptRecord。		 讀取
attributePrefix 屬性的前置詞，用於區分屬性與元素。 這將是欄位名稱的前置詞。 預設值為 _。 讀取 XML 時可以為空，但寫入時不能為空。 讀、寫
valueTag 用於包含屬性或子元素的元素中字元資料的標籤。 使用者可以在結構描述中指定 valueTag 欄位，或者當字元資料存在於具有其他元素或屬性的元素中時，該欄位將在結構描述推斷期間自動新增。 預設：_VALUE 閱讀、書寫
encoding 讀取時，依指定的編碼類型解碼 XML 檔案。 對於寫入，請指定已儲存 XML 檔案的編碼 (字元集)。 XML 內建函數會略過此選項。 預設值：UTF-8。 讀、寫
ignoreSurroundingSpaces 定義是否應忽略被讀取值周圍的空白。 預設值：true。 僅由空白字元組成的字元資料會被忽略。 讀取
rowValidationXSDPath 用於驗證每個資料列的 XML 的可選 XSD 檔案路徑。 無法驗證的資料列視為上述剖析錯誤。 XSD 不會以其他方式影響提供或推斷的結構描述。 讀取
ignoreNamespace 如果 true為 ，則會忽略 XML 元素和屬性上的命名空間前置詞。 例如，標籤 <abc:author> 和 <def:author> 視為兩者都只是 <author>。 無法忽略 rowTag 元素上的命名空間，只能忽略其可讀子元素。 即使存在false，XML 剖析也不會識別命名空間。 預設值：false。 讀取
timestampFormat 遵循 日期時間模式 格式的自定義時間戳格式字串。 這適用於 timestamp 類型。 預設值：yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]。 讀、寫
timestampNTZFormat 遵循日期時間模式格式的不含時區的自訂時間標記格式字串。 這適用於 TimestampNTZType 類型。 預設：
yyyy-MM-dd'T'HH:mm:ss[.SSS]		 讀、寫
dateFormat 遵循 日期時間模式 格式的自訂日期格式字串。 這適用於日期類型。 預設值：yyyy-MM-dd。 讀、寫
locale 將地區語言標籤設為 IETF BCP 47 格式。 例如，在剖析日期和時間戳記時使用 locale。 預設值：en-US。 讀取
rootTag XML 檔案的根標籤。 例如，在 <books> <book><book>...</books> 中，適當的值為 books。 您可以透過指定類似 books foo="bar" 的值來包含基本屬性。 預設值：ROWS。 寫入
declaration 要在每個輸出 XML 檔案的開頭 (在 rootTag 之前) 寫入的 XML 宣告內容。 例如，foo 的值會導致寫入 <?xml foo?>。 設定空字串以隱藏。 預設：version="1.0"
encoding="UTF-8" standalone="yes"。		 寫入
arrayElementName 寫入時將陣列值資料行的每個元素括起來的 XML 元素的名稱。 預設值：item。 寫入
nullValue 設定 null 值的字串表示法。 預設值：字串 null。 當這是 null 時，剖析器不會為欄位寫入屬性和元素。 讀、寫
compression 儲存至檔案時使用的壓縮碼。 這可以是已知不區分大小寫的縮寫名稱之一 (none、bzip2、gzip、lz4、snappy 和
deflate)。 XML 內建函數會略過此選項。 預設值：none。		 寫入
validateName 如果為 true，則當 XML 元素名稱驗證失敗時擲回錯誤。 例如，SQL 欄位名稱可以有空格，但 XML 元素名稱不能有空格。 預設：
true。		 寫入
readerCaseSensitive 指定在啟用 rescuedDataColumn 時如何處理區分大小寫的行為。 如果為 true，則修復名稱因大小寫不同而與架構不匹配的資料行；否則，請不區分大小寫地讀取資料。 預設值：true。 讀取
rescuedDataColumn 是否要將所有因數據類型不符和結構不符（包括欄位大小寫）而無法解析的數據，收集到一個獨立的欄位。 使用自動載入器時，系統會預設包含這個欄位。 如需詳細資訊，請參閱 什麼是復原的數據欄？。
COPY INTO （舊版） 不支援已獲救的數據行，因為您無法使用 COPY INTO手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
預設值：無。		 讀取
singleVariantColumn 指定單一變體資料列的名稱。 如果指定這個選項來讀取，請將整個 XML 記錄剖析成單一 Variant 資料行，並將指定的選項字串值當做數據行的名稱。 如果提供此選項來寫入，請將單一 Variant 資料行的值寫入 XML 檔案。 預設值：none。 讀、寫

PARQUET 選項

選項
datetimeRebaseMode
類型:String
控制 DATE 和 TIMESTAMP 值在儒略曆與前置格里曆之間的基準變換。 允許的值：EXCEPTION、LEGACY 和
CORRECTED。
預設值：LEGACY
int96RebaseMode
類型:String
控制 INT96 時間戳記值在儒略曆與前置格里高利曆之間的重新基準化。 允許的值：EXCEPTION、LEGACY 和
CORRECTED。
預設值：LEGACY
mergeSchema
類型:Boolean
是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。
預設值：false
readerCaseSensitive
類型:Boolean
指定啟用 rescuedDataColumn 時的大小寫敏感行為。 如果為 true，則修復名稱因大小寫不同而與架構不匹配的資料行；否則，請不區分大小寫地讀取資料。
預設值：true
rescuedDataColumn
類型:String
是否要收集因下列原因而無法剖析的所有數據：數據類型不匹配，以及結構不匹配（包括欄位大小寫）到個別的欄位。 使用自動載入器時，系統會預設包含這個欄位。 如需詳細資訊，請參閱 什麼是修復的數據欄？。
COPY INTO （舊版） 不支援已獲救的數據行，因為您無法使用 COPY INTO手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
預設值：無

AVRO 選項

選項
avroSchema
類型:String
使用者以 Avro 格式提供的可選模式。 讀取 Avro 時，可以將此選項設定為一個演進的結構描述，該結構描述與實際 Avro 結構描述相容但不同。 反序列化結構描述將與演進的結構描述保持一致。 例如，如果您設定的演進結構描述包含一個具有預設值的其他資料行，則讀取結果也會包含該新資料行。
預設值：無
datetimeRebaseMode
類型:String
控制 DATE 和 TIMESTAMP 值在儒略曆與前置格里曆之間的基準變換。 允許的值：EXCEPTION、LEGACY 和
CORRECTED。
預設值：LEGACY
mergeSchema
類型:Boolean
是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。
Avro 的 mergeSchema 無法簡化資料類型。
預設值：false
readerCaseSensitive
類型:Boolean
指定啟用 rescuedDataColumn 時的大小寫敏感行為。 如果為 true，則修復名稱因大小寫不同而與架構不匹配的資料行；否則，請不區分大小寫地讀取資料。
預設值：true
rescuedDataColumn
類型:String
是否要收集因下列原因而無法剖析的所有數據：數據類型不匹配，以及結構不匹配（包括欄位大小寫）到個別的欄位。 使用自動載入器時，系統會預設包含這個欄位。
COPY INTO （舊版） 不支援已獲救的數據行，因為您無法使用 COPY INTO手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
如需詳細資訊，請參閱 什麼是修復的數據欄？。
預設值：無

BINARYFILE 選項

二進位檔案沒有任何額外的組態選項。

TEXT 選項

選項
encoding
類型:String
TEXT 檔案行分隔符編碼的名稱。 請參閱java.nio.charset.Charset以取得選項清單。
檔案的內容不會受到這個選項的影響，而且會讀取 as-is。
預設值：UTF-8
lineSep
類型:String
兩筆連續 TEXT 記錄之間的字串。
預設值：無，其中涵蓋 \r、\r\n 和 \n
wholeText
類型:Boolean
是否要將檔案讀取為單一記錄。
預設值：false

ORC 選項

選項
mergeSchema
類型:Boolean
是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。
預設值：false

雲端特定選項

自動載入器提供許多用於設定雲端基礎結構的選項。

AWS 特定選項

只有在你選擇 cloudFiles.useNotifications = true 並希望自動載入者幫你設定通知服務時，才提供以下選項：

選項
cloudFiles.region
類型:String
S3 貯體之所在區域，以及將建立 AWS SNS 和 SQS 服務的地區。
預設值：EC2 實例的區域。
cloudFiles.restrictNotificationSetupToSameAWSAccountId
類型:Boolean
僅允許來自與 SNS 主題相同帳戶中的 AWS S3 儲存桶的事件通知。 如果設定為 true，「Auto Loader」只會接受來自與 SNS 主題位於相同帳戶中的 AWS S3 收集桶的事件通知。
當 false 時，存取政策不會限制跨帳戶的儲存桶和 SNS 主題設定。 當 SNS 主題和儲存桶路徑與不同帳戶相關聯時，這很有用。
適用於 Databricks Runtime 17.2 和更新版本。
預設：false

只有在您選擇 cloudFiles.useNotifications = true 且希望自動載入器使用您已設定的佇列時，才提供下列選項：

選項
cloudFiles.queueUrl
類型:String
SQS 佇列的 URL。 如果提供此選項，則自動載入器會直接取用此佇列中的事件，而不是設定自己的 AWS SNS 和 SQS 服務。
默認值：無

AWS 驗證選項

提供下列驗證選項，以使用 Databricks 服務認證：

選項
databricks.serviceCredential
類型:String
Databricks 服務認證的名稱。 適用於 Databricks Runtime 16.1 和更新版本。
默認值：無

當 Databricks 服務認證或 IAM 角色無法使用時，您可以改為提供下列驗證選項：

選項
cloudFiles.awsAccessKey
類型:String
使用者的 AWS 存取金鑰識別碼。 必須提供cloudFiles.awsSecretKey。
默認值：無
cloudFiles.awsSecretKey
類型:String
使用者的 AWS 祕密存取金鑰。 必須提供cloudFiles.awsAccessKey。
默認值：無
cloudFiles.roleArn
類型:String
如有需要，要承擔之 IAM 角色的 ARN。 您可以透過叢集的實例設定檔或提供 cloudFiles.awsAccessKey 和 cloudFiles.awsSecretKey 的憑證來採取角色。
默認值：無
cloudFiles.roleExternalId
類型:String
使用 cloudFiles.roleArn 擔任角色時所需提供的識別碼。
默認值：無
cloudFiles.roleSessionName
類型:String
在使用 cloudFiles.roleArn 假設角色時，可以選擇性地使用的會話名稱。
默認值：無
cloudFiles.stsEndpoint
類型:String
一個可選的端點，用於在使用 cloudFiles.roleArn 假設角色時存取 AWS STS。
默認值：無

Azure 特定選項

如果您指定 cloudFiles.useNotifications = true，並且希望自動載入器設定通知服務，則必須為下列所有選項提供值：

選項
cloudFiles.resourceGroup
類型:String
在其下建立儲存體帳戶的 Azure 資源群組。
默認值：無
cloudFiles.subscriptionId
類型:String
用於建立資源群組的 Azure 訂閱識別碼。
默認值：無
databricks.serviceCredential
類型:String
Databricks 服務認證的名稱。 適用於 Databricks Runtime 16.1 和更新版本。
默認值：無

如果 Databricks 服務認證無法使用，您可以改為提供下列驗證選項：

選項
cloudFiles.clientId
類型:String
服務主體的用戶端識別碼或應用程式識別碼。
默認值：無
cloudFiles.clientSecret
類型:String
服務主體的用戶端密鑰。
默認值：無
cloudFiles.connectionString
類型:String
儲存體帳戶的連接字串，基於帳戶存取金鑰或共用存取簽章 (SAS)。
默認值：無
cloudFiles.tenantId
類型:String
用於建立服務主體的 Azure 租用戶識別碼。
默認值：無

重要

使用 Databricks Runtime 9.1 和更新版本可在 Azure 中國和政府區域中使用自動通知設定。 對於較舊的 DBR 版本，您必須在這些區域中提供 queueName，才能將自動載入器與檔案通知搭配使用。

只有在您選擇 cloudFiles.useNotifications = true 且希望自動載入器使用您已設定的佇列時，才提供下列選項：

選項
cloudFiles.queueName
類型:String
Azure 佇列的名稱。 如果提供此選項，則雲端檔案來源將直接取用此佇列中的事件，而不是設定自身的 Azure 事件方格和佇列儲存體服務。 在此情況下，您的 databricks.serviceCredential 或 cloudFiles.connectionString 只需具有佇列的讀取權限。
默認值：無

Google 特定選項

自動載入器可利用 Databricks 服務認證自動為您設定通知服務。 使用 Databricks 服務認證建立的服務帳戶將需要在 檔案通知模式中設定自動載入器數據流中指定的許可權。

選項
cloudFiles.projectId
類型:String
GCS 儲存桶所在的專案識別碼。 Google Cloud Pub/Sub 訂用帳戶也會在此專案內建立。
默認值：無
databricks.serviceCredential
類型:String
Databricks 服務認證的名稱。 適用於 Databricks Runtime 16.1 和更新版本。
默認值：無

如果 Databricks 服務認證無法使用，您可以直接使用 Google 服務帳戶。 您可以依照 Google 服務設定 來設定叢集來假設服務帳戶，或直接提供下列驗證選項：

選項
cloudFiles.client
類型:String
Google 服務帳戶的用戶端識別碼。
默認值：無
cloudFiles.clientEmail
類型:String
Google 服務帳戶的電子郵件。
默認值：無
cloudFiles.privateKey
類型:String
針對Google服務帳戶產生的私鑰。
默認值：無
cloudFiles.privateKeyId
類型:String
針對Google服務帳戶產生的私鑰標識碼。
默認值：無

只有在您選擇 cloudFiles.useNotifications = true 且希望自動載入器使用您已設定的佇列時，才提供下列選項：

選項
cloudFiles.subscription
類型:String
Google Cloud Pub/Sub 訂用帳戶的名稱。 如果提供此選項，則雲端檔案來源將取用此佇列中的事件，而不是設定自身的 GCS 通知和 Google Cloud Pub/Sub 服務。
默認值：無
  • Last updated on