自動載入器選項

文章
10/14/2024

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

常見自動載入器選項
目錄清單選項
檔案通知選項
檔案格式選項
雲端特定選項

常見自動載入器選項

您可以為目錄清單或檔案通知模式設定下列選項。

選項
`cloudFiles.allowOverwrites` 類型:`Boolean` (英文) 是否允許輸入目錄檔案變更以覆寫現有的資料。此設定的啟用需要注意幾個事項。如需詳細資料，請參閱自動載入器是否會在檔案附加或覆寫時再次處理檔案？。預設值：`false`
`cloudFiles.backfillInterval` 類型:`Interval String` (英文) 自動載入器可以在指定的間隔觸發非同步回填，例如，`1 day` 表示每天回填一次，`1 week` 表示每週回填一次。檔案事件通知系統不保證 100% 交付已上傳的所有檔案，因此您可以使用回填來保證所有檔案最終都得到處理，此功能在 Databricks Runtime 8.4 (EoS) 和更新版本中可用。預設值：無
`cloudFiles.format` 類型:`String` (英文) 來源路徑中的資料檔案格式。允許的值包括： - `avro`：Avro 檔案 - `binaryFile`：二進位檔案 - `csv`：讀取 CSV 檔案 - `json`：JSON 檔案 - `orc`：ORC 檔案 - `parquet`：使用 Azure Databricks 讀取 Parquet 檔案 - `text`：文字檔預設值：無 (必要選項)
`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`。對於 `file2.csv` 和 `file3.csv`，將正確剖析 `month` 和 `day`。預設值：無
`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` (英文) 是否驗證自動載入器選項，並為未知或不一致的選項傳回錯誤。預設值：`true`

目錄清單選項

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

選項

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

cloudFiles.useIncrementalListing (已取代)

類型:String (英文)

這個功能已被取代。 Databricks 建議使用檔案通知模式，而不是
cloudFiles.useIncrementalListing。

是否在目錄清單模式下使用累加式清單，而不是完整列表。根據預設，自動載入器竭盡所能自動偵測指定目錄是否適用於累加式清單。您可以明確使用累加式清單，或者透過將完整目錄清單分別設定為 true 或 false 來使用該清單。

不正確地在非依詞彙排序的目錄上啟用累加式清單會阻止自動載入器探索新檔案。

適用於 Azure Data Lake Storage Gen2 (abfss://)、S3 (s3://) 和 GCS (gs://)。

在 Databricks Runtime 9.1 LTS 和更新版本中可用。

預設值：auto

可用值：auto、true、false

檔案通知選項

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

選項
`cloudFiles.fetchParallelism` 類型:`Integer` (英文) 從佇列服務擷取訊息時要使用的執行緒數目。預設值：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.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.useNotifications` 類型:`Boolean` (英文) 是否使用檔案通知模式來確定何時存在新檔案。如果為 `false`，則使用目錄清單模式。請參閱比較自動載入器檔案偵測模式。預設值：`false`

(1) 根據預設，自動載入器會盡全力新增下列索引鍵/值標籤組：

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

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

檔案格式選項

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

泛型選項
JSON 選項
CSV 選項
XML 選項
PARQUET 選項
AVRO 選項
BINARYFILE 選項
TEXT 選項
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 模式。相當於 `COPY INTO` 中的 `PATTERN`。 `fileNamePattern` 可以在 `read_files` 中使用。預設值：無
`recursiveFileLookup` 類型:`Boolean` (英文) 是否在結構描述推斷期間略過分割推斷。這不會影響載入的檔案。預設值：`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 字串包含未逸出的控制字元 (值小於 32 的 ASCII 字元，包括定位字元和換行字元)。預設值：`false`
`allowUnquotedFieldNames` 類型:`Boolean` (英文) 是否允許使用未加上引號的欄位名稱 (JavaScript 允許，但 JSON 規格不允許)。預設值：`false`
`badRecordsPath` 類型:`String` (英文) 用於記錄有關錯誤 JSON 記錄的資訊的檔案儲存路徑。預設值：無
`columnNameOfCorruptRecord` 類型:`String` (英文) 儲存格式錯誤且無法剖析的記錄的資料行。如果用於剖析的 `mode` 設定為 `DROPMALFORMED`，則此資料行將為空。預設值：`_corrupt_record`
`dateFormat` 類型:`String` (英文) 用於剖析日期字串的格式。預設值：`yyyy-MM-dd`
`dropFieldIfAllNull` 類型:`Boolean` (英文) 是否要在結構描述推斷期間略過所有 Null 值或空陣列和結構的資料行。預設值：`false`
`encoding` 或 `charset` 類型:`String` (英文) JSON 檔案編碼的名稱。如需選項清單，請參閱 `java.nio.charset.Charset`。當 `multiline` 為 `true` 時，您無法使用 `UTF-16` 和 `UTF-32`。預設值：`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` (英文) 是否將因資料類型不符或結構描述不符 (包括資料行大小寫) 而無法剖析的所有資料收集至個別資料行。使用自動載入器時，預設包含此資料行。如需詳細資料，請參閱什麼是修復的資料行？。預設值：無
`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]`，並擲回錯誤，因為它找不到右引號。 - 如果要逸出 `'\'` 的字元定義為 `'\'`，則讀取的記錄會帶有 2 個值：`[a\]` 和 `[b]`。預設值：`'\0'`
`columnNameOfCorruptRecord` > [!NOTE] >> 支援自動載入器。不支援 `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` 為 `true` 時，不能使用 `multiline` 和 `UTF-32`。預設值：`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` (英文) Null 值的字串表示法。預設值：`""`
`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` (英文) 是否將因資料類型不符和結構描述不符 (包括資料行大小寫) 而無法剖析的所有資料收集至個別資料行。使用自動載入器時，預設包含此資料行。如需詳細資料，請參閱什麼是修復的資料行？。預設值：無
`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` 選項

選項	描述	範圍
`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`	選用 XSD 檔案的路徑，用於個別驗證每個資料列的 XML。無法驗證的資料列視為上述剖析錯誤。 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`。	write
`declaration`	要在每個輸出 XML 檔案的開頭 (在 `rootTag` 之前) 寫入的 XML 宣告內容。例如，`foo` 的值會導致寫入 `<?xml foo?>`。設定空字串以隱藏。預設值：`version="1.0"` `encoding="UTF-8" standalone="yes"`。	write
`arrayElementName`	寫入時將陣列值資料行的每個元素括起來的 XML 元素的名稱。預設值：`item`。	write
`nullValue`	設定 null 值的字串表示法。預設值：字串 `null`。當這是 `null` 時，剖析器不會為欄位寫入屬性和元素。	讀取、寫入
`compression`	儲存至檔案時使用的壓縮碼。這可以是已知不區分大小寫的縮寫名稱之一 (`none`、`bzip2`、`gzip`、`lz4`、`snappy` 和 `deflate`)。 XML 內建函數會略過此選項。預設值：`none`。	write
`validateName`	如果為 true，則當 XML 元素名稱驗證失敗時擲回錯誤。例如，SQL 欄位名稱可以有空格，但 XML 元素名稱不能有空格。預設值： `true`。	write
`readerCaseSensitive`	指定啟用 rescuedDataColumn 時區分大小寫的行為。如果為 true，則修復名稱因大小寫而與結構描述不同的資料行；否則，請以不區分大小寫的方式讀取資料。預設值：`true`。	已讀
`rescuedDataColumn`	是否將因資料類型不符和結構描述不符 (包括資料行大小寫) 而無法剖析的所有資料收集至個別資料行。使用自動載入器時，預設包含此資料行。如需詳細資料，請參閱什麼是修復的資料行？。預設值：無。	已讀

`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` (英文) 是否將因資料類型不符和結構描述不符 (包括資料行大小寫) 而無法剖析的所有資料收集至個別資料行。使用自動載入器時，預設包含此資料行。如需詳細資料，請參閱什麼是修復的資料行？。預設值：無

`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` (英文) 是否將因資料類型不符和結構描述不符 (包括資料行大小寫) 而無法剖析的所有資料收集至個別資料行。使用自動載入器時，預設包含此資料行。如需詳細資料，請參閱什麼是修復的資料行？。預設值：無

`BINARYFILE` 選項

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

`TEXT` 選項

選項
`encoding` 類型:`String` (英文) TEXT 檔案編碼的名稱。如需選項清單，請參閱 `java.nio.charset.Charset`。預設值：`UTF-8`
`lineSep` 類型:`String` (英文) 兩筆連續 TEXT 記錄之間的字串。預設值：無，其中涵蓋 `\r`、`\r\n` 和 `\n`
`wholeText` 類型:`Boolean` (英文) 是否要將檔案讀取為單一記錄。預設值：`false`

`ORC` 選項

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

雲端特定選項

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

AWS 特定選項
Azure 特定選項
Google 特定選項

AWS 特定選項

只有在您選擇 cloudFiles.useNotifications = true 且希望自動載入器為您設定通知服務時，才提供下列選項：

選項
`cloudFiles.region` 類型:`String` (英文) 來源 S3 貯體所在的、將建立 AWS SNS 和 SQS 服務的區域。預設值：EC2 執行個體的區域。

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

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

當 IAM 角色不可用或從不同雲端擷取資料時，您可以使用下列選項提供用於存取 AWS SNS 和 SQS 的認證。

選項
`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.clientId` 類型:`String` (英文) 服務主體的用戶端識別碼或應用程式識別碼。預設值：無
`cloudFiles.clientSecret` 類型:`String` (英文) 服務主體的用戶端密碼。預設值：無
`cloudFiles.connectionString` 類型:`String` (英文) 儲存體帳戶的連接字串，基於帳戶存取金鑰或共用存取簽章 (SAS)。預設值：無
`cloudFiles.resourceGroup` 類型:`String` (英文) 在其下建立儲存體帳戶的 Azure 資源群組。預設值：無
`cloudFiles.subscriptionId` 類型:`String` (英文) 在其下建立資源群組的 Azure 訂用帳戶識別碼。預設值：無
`cloudFiles.tenantId` 類型:`String` (英文) 在其下建立服務主體的 Azure 租用戶識別碼。預設值：無

重要

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

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

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

Google 特定選項

自動載入器可以利用 Google 服務帳戶自動為您設定通知服務。您可以遵循 Google 服務設定，將叢集設定為採用服務帳戶。什麼是自動載入器檔案通知模式？中指定了服務帳戶所需的權限。否則，如果您希望自動載入器為您設定通知服務，才提供下列選項。

選項
`cloudFiles.client` 類型:`String` (英文) Google 服務帳戶的用戶端識別碼。預設值：無
`cloudFiles.clientEmail` 類型:`String` (英文) Google 服務帳戶的電子郵件。預設值：無
`cloudFiles.privateKey` 類型:`String` (英文) 為 Google 服務帳戶產生的私密金鑰。預設值：無
`cloudFiles.privateKeyId` 類型:`String` (英文) 為 Google 服務帳戶產生的私密金鑰識別碼。預設值：無
`cloudFiles.projectId` 類型:`String` (英文) GCS 貯體所在的專案識別碼。 Google Cloud Pub/Sub 訂用帳戶也會在此專案內建立。預設值：無

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

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

分享方式：

自動載入器選項

常見自動載入器選項

目錄清單選項

檔案通知選項

檔案格式選項

泛型選項

`JSON` 選項

`CSV` 選項

`XML` 選項

`PARQUET` 選項

`AVRO` 選項

`BINARYFILE` 選項

`TEXT` 選項

`ORC` 選項

雲端特定選項

AWS 特定選項

Azure 特定選項

Google 特定選項

意見反映

更多資源

分享方式：

自動載入器選項

常見自動載入器選項

目錄清單選項

檔案通知選項

檔案格式選項

泛型選項

JSON 選項

CSV 選項

XML 選項

PARQUET 選項

AVRO 選項

BINARYFILE 選項

TEXT 選項

ORC 選項

雲端特定選項

AWS 特定選項

Azure 特定選項

Google 特定選項

意見反映

更多資源

`JSON` 選項

`CSV` 選項

`XML` 選項

`PARQUET` 選項

`AVRO` 選項

`BINARYFILE` 選項

`TEXT` 選項

`ORC` 選項