Spark API 選項參考

本頁列出 Spark API 可讀寫資料的可用輸入與輸出選項。

DataFrameReader 選項

請搭配 DataFrameReader.option()、DataFrameReader.options()、read_files、COPY INTO 以及 Auto Loader 來控制 Azure Databricks 如何讀取資料檔案。

Example

以下範例設定 multiLine 為用於 True 讀取 JSON 檔案：

Python

df = spark.read.format("json").option("multiLine", True).load("/path/to/data")

Scala

val df = spark.read.format("json").option("multiLine", "true").load("/path/to/data")

SQL

SELECT * FROM read_files("/path/to/data", format => "json", multiLine => true)

常見

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

鑰匙	預設值	Description
`ignoreCorruptFiles`	`false`	是否要略過損毀的檔案。如果為 true，則 Spark 作業會在遇到損毀的檔案時繼續執行，而且仍然會傳回已讀取的內容。對於 `COPY INTO`，你可以觀察到跳過且損壞的檔案，就像 `numSkippedCorruptFiles` Delta Lake 歷史的欄位一樣 `operationMetrics` 。在 Databricks Runtime 11.3 LTS 和更新版本中可用。
`ignoreMissingFiles`	`false` 針對 Auto Loader， `true` 代表 `COPY INTO` （舊有）	是否略過遺漏的檔案。如果屬實，Spark 工作在遇到遺失檔案時仍會繼續執行，且內容仍會被回傳。在 Databricks Runtime 11.3 LTS 和更新版本中可用。
`modifiedAfter`	None	使用可選擇的時間戳作為篩選條件，只處理在提供的時間戳之後具有修改時間戳的檔案。
`modifiedBefore`	None	選用一個時間戳作為篩選條件，只匯入修改時間戳在提供的時間戳之前的檔案。
`pathGlobFilter` 或 `fileNamePattern`	None	潛在的 Glob 模式，用於選擇檔案。相當於 `PATTERN` （舊有）中的 `COPY INTO` 。 `fileNamePattern` 可以在 `read_files` 中使用。
`recursiveFileLookup`	`false`	當 `true`時，即使巢狀目錄名稱不遵循分割 `date=2019-07-01`區命名方案，此選項仍可搜尋巢狀目錄。

阿弗羅

鑰匙	預設值	Description
`avroSchema`	None	使用者以 Avro 格式提供的可選模式。讀取 Avro 時，這個選項可以設定為一個演變後的架構，該架構與實際 Avro 架構相容但有所不同。反序列化結構與演化後的架構是一致的。例如，如果你設定一個演化後的結構，包含一個預設值的額外欄位，讀取結果也會包含新的欄位。
`avroSchemaEvolutionMode`	`none`	如何使用結構登錄檔處理結構演化。有效值： `none` （忽略結構變更並繼續工作）、 `restart` （當偵測到結構變更時，會觸發並 `UnknownFieldException` 需要重新啟動工作）。
`datetimeRebaseMode`	`LEGACY`	控制 DATE 和 TIMESTAMP 值在儒略曆與前置格里曆之間的基準變換。有效值：`EXCEPTION`、`LEGACY` 和 `CORRECTED`。
`enableStableIdentifiersForUnionType`	`false`	是否應該為 Avro Union 類型使用穩定欄位名稱。啟用時，聯集型態欄位名稱會從小寫的型別名稱衍生而來（例如， `member_int`， `member_string`）。若兩個類型名稱在縮小後相同，則拋出例外。
`mergeSchema`	`false`	是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。 `mergeSchema` 對於 Avro 來說，資料類型不會被放寬。
`mode`	`FAILFAST`	解析器模式用於處理損壞的紀錄。有效值： `FAILFAST` （拋出例外）、 `PERMISSIVE` （將錯誤欄位設為 null）、 `DROPMALFORMED` （無聲丟棄壞紀錄）。
`readerCaseSensitive`	`true`	指定啟用 `rescuedDataColumn` 時的大小寫敏感行為。若屬實，則救出與結構中名稱不同的資料欄位。若錯誤，則以不區分大小寫的方式讀取資料。
`recursiveFieldMaxDepth`	None	遞迴 Avro 場的最大遞迴深度。設為 `1` 截斷所有遞迴欄位， `2` 允許一層遞迴，依此類推最高至 `15`。當未設定或 `0`時，不允許遞迴欄位。有效值： `0` 到 `15`。
`rescuedDataColumn`	None	是否要收集因下列原因而無法剖析的所有數據：數據類型不匹配，以及結構不匹配（包括欄位大小寫）到個別的欄位。使用自動載入器時，系統會預設包含這個欄位。 `COPY INTO` （舊版）不支援已獲救的數據行，因為您無法使用 `COPY INTO`手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。如需詳細資訊，請參閱什麼是修復的數據欄？。
`stableIdentifierPrefixForUnionType`	`member_`	當 `enableStableIdentifiersForUnionType=true`時，穩定聯集類型欄位名稱的前綴。

CSV

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

Excel

鑰匙	預設值	Description
`dataAddress`	None	Excel 語法中要讀取的儲存格範圍。若省略，則讀取第一張圖中所有有效儲存格。用來 `"SheetName!C5:H10"` 讀取指定工作表的範圍、 `"C5:H10"` 讀取第一張工作表的範圍，或 `"SheetName"` 是讀取特定工作表中的所有資料。
`headerRows`	`0`	欄位名稱標頭的初始列數。當 `dataAddress` 指定時，這適用於細胞範圍內。當 `0`時，欄位名稱自動生成為 `_c1`、 `_c2`、 `_c3`、等。有效值： `0`， `1`。
`ignoreMissingSheet`	`false`	是否要靜默跳過不包含由 `dataAddress`所指定的工作表的檔案。當 `false`時，若檔案缺少所請求的圖紙，則會拋出錯誤。僅當圖表名稱在中 `dataAddress`指定時才適用。有效值： `true`， `false`。
`includePhoneticRuns`	`false`	是否要在閱讀 XLSX 檔案時，將拼音或振假名（拼音或振假名）串接到儲存格字串值。有效值： `true`， `false`。
`operation`	`readSheet`	在 Excel 工作簿上執行的操作。有效值： `readSheet` （從工作表讀取資料）、 `listSheets` （回傳一個包含欄位 `sheetIndex: long` 和 `sheetName: String` 的結構體，對每個工作表）。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	自訂格式字串，用於無時區時間戳記值，以字串形式儲存在 Excel 中。自訂日期格式會遵循 Datetime 模式的格式。
`dateFormat`	`yyyy-MM-dd`	字串值的自訂格式字串可讀作 `Date`。自訂日期格式會遵循 Datetime 模式的格式。

JSON

鑰匙	預設值	Description
`allowBackslashEscapingAnyCharacter`	`false`	是否允許反斜線逸出其後面的任何字元。如果未啟用，則只能轉譯 JSON 規格中明確列出的字元。
`allowComments`	`false`	是否允許在剖析的內容中使用 Java、C 和 C++ 樣式註解 (`'/'`、`'*'` 和 `'//'` 變體)。
`allowNonNumericNumbers`	`true`	是否允許將非數字 (`NaN`) 標記集用作合法浮點數數值。
`allowNumericLeadingZeros`	`false`	是否允許整數以附加的 (可略過的) 零開頭 (例如 `000001`)。
`allowSingleQuotes`	`true`	是否允許使用單引號 (撇號字元 `'\'`) 來引用字串 (名稱和字串值)。
`allowUnquotedControlChars`	`false`	是否允許 JSON 字串包含未轉義的控制字元（值小於 32 的 ASCII 字元，包括定位字元和換行字元）。
`allowUnquotedFieldNames`	`false`	是否允許使用無引號欄位名稱，這是 JavaScript 允許的，但 JSON 規範不允許。
`alternateVariantEncoding`	None	原始碼 JSON 中 Variant 值所使用的編碼方式。設為以 `Z85` 解碼以 Base85 編碼而非內嵌 JSON 儲存的 Variant 值。
`badRecordsPath`	None	用於記錄有關錯誤 JSON 記錄的資訊的檔案儲存路徑。在檔案型資料來源中使用 `badRecordsPath` 選項具有以下限制：這是非交易式，可能會導致結果不一致。暫時性錯誤會被視為失敗。
`columnNameOfCorruptRecord`	`_corrupt_record`	儲存格式錯誤且無法解析的記錄的欄位。如果用於剖析的 `mode` 設定為 `DROPMALFORMED`，則此資料行將為空。
`dateFormat`	`yyyy-MM-dd`	用於剖析日期字串的格式。
`dropFieldIfAllNull`	`false`	是否在結構推斷過程中略過所有為 Null 值或空陣列和結構的欄位。
`encoding` 或 `charset`	`UTF-8`	JSON 檔案編碼的名稱。如需選項清單，請參閱 `java.nio.charset.Charset`。當 `UTF-16` 為 `UTF-32` 時，您無法使用 `multiline` 和 `true`。
`inferTimestamp`	`false`	是否嘗試將時間戳記字串推斷為 `TimestampType`。當設定為 `true`時，結構推論可能會明顯花更長時間。您必須啟用 `cloudFiles.inferColumnTypes`，才能與自動載入器搭配使用。
`lineSep`	無，涵蓋 `\r`、 `\r\n`和 `\n`	兩筆連續 JSON 記錄之間的字串。
`locale`	`US`	`java.util.Locale` 識別碼。影響 JSON 中的預設日期、時間戳記和小數解析。
`maxNestingDepth`	`500`	JSON 物件與陣列的最大允許巢狀深度。對於深度巢狀文件，則提高此值。有效值：正整數。
`maxNumLen`	`1000`	JSON 輸入中數字標記的最大長度。對於 JSON 的數值值增加，並使用較大的數值。有效值：正整數。
`maxStringLen`	無限制	JSON 輸入中字串值的最大長度。設定在解析大字串的 JSON 時限制記憶體使用。有效值：正整數。
`mode`	`PERMISSIVE`	用於處理格式錯誤記錄的解析器模式。有效值： `PERMISSIVE`， `DROPMALFORMED`， `FAILFAST`。
`multiLine`	`false`	JSON 記錄是否跨越多行。
`prefersDecimal`	`false`	如果可能，嘗試將字串推斷為 `DecimalType` 類型，而不是浮點數或雙精度數類型。你也必須使用結構推論，無論是啟用 `inferSchema` 還是 `cloudFiles.inferColumnTypes` 搭配自動載入器。
`primitivesAsString`	`false`	是否將數字和布林值等基本類型推斷為 `StringType`。
`readerCaseSensitive`	`true`	指定啟用 `rescuedDataColumn` 時的大小寫敏感行為。若屬實，則救出與結構中名稱不同的資料欄位。若錯誤，則以不區分大小寫的方式讀取資料。可在 Databricks 執行環境 13.3 及以上版本中取得。
`rescuedDataColumn`	None	是否要將因資料型別不匹配或結構不符（包括欄位分類）而無法解析的資料收集到獨立欄位。使用自動載入器時，系統會預設包含這個欄位。如需詳細資料，請參閱什麼是復原的資料欄位？。 `COPY INTO` （舊版）不支援已獲救的數據行，因為您無法使用 `COPY INTO`手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
`singleVariantColumn`	None	是否要將整個 JSON 文件匯入，解析成一個以指定字串為欄位名稱的單一 Variant 欄位。若未設定，JSON 欄位會被匯入各自的欄位。有效值：任意字串。
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	用於剖析時間戳記字串的格式。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	無時區（`TimestampNTZType`）字串時段的解析時間戳格式。
`timeZone`	None	用於解析時間戳記和日期的 `java.time.ZoneId`。
`upgradeExceptionAsBadRecord`	`false`	是否應該將類型升級例外（例如無法擴大到宣告欄位類型）視為壞紀錄，而非拋出例外。

卡夫卡

欲了解完整的 Kafka 閱讀器選項清單，請參見 DataStreamReader Kafka 選項。以下選項僅適用於使用 spark.read.format("kafka")。

鑰匙	預設值	Description
`endingOffsets`	`latest`	該在哪裡停止閱讀。有效值： `latest`，或每個分割區的 JSON 偏移量字串，例如 `{"topicA":{"0":50,"1":-1}}`。在 JSON 字串中，是 `-1` 最新的偏移量。 `-2`，即最早的偏移，不被允許作為結束偏移。
`endingOffsetsByTimestamp`	None	每個分區結束的偏移量以毫秒為單位的時間戳記。有效值：每個分割區的時間戳記 JSON 字串，例如 `{"topicA":{"0":2000,"1":3000}}`。
`endingTimestamp`	None	全域結束時間戳以毫秒計，適用於所有分割區。有效值：非負整數。

奧爾克

鑰匙	預設值	Description
`mergeSchema`	`false`	是否要跨多個檔案推斷結構描述，以及合併每個檔案的結構描述。

拼花地板

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

州商店

使用這些選項或 spark.read.format("statestore")read_statestore table-valued 函式來讀取結構化串流狀態資料。請參閱讀取結構化串流狀態資訊。

鑰匙	預設值	Description
`batchId`	最新批次識別碼	目標批次要讀取。用來查詢查詢的早期狀態。必須提交批次，但尚未進行清理。有效值：非負整數。
`operatorId`	`0`	目標操作員的讀取。當查詢包含多個具狀態運算子時使用。有效值：非負整數。
`storeName`	`DEFAULT`	讀取目標州商店名稱。當有狀態運算子擁有多個狀態儲存實例時，才會使用。串流與串流的連接必須指定其中之一 `storeName` 或 `joinSide` ，但不能同時指定。有效值：任意字串。
`joinSide`	None	目標端是用來讀取串流-串流連接的那一端。串流與串流的連接必須指定其中之一 `storeName` 或 `joinSide` ，但不能同時指定。有效值： `left`， `right`。
`snapshotStartBatchId`	None	快照的批次 ID，作為讀取狀態的起點。讀取器透過重播從快照到 `batchId`的變更來重建狀態。當快照損壞時，這很有用。必須與一起 `snapshotPartitionId`指定。無法使用 `readChangeFeed`。支援 HDFS 支援的狀態儲存庫，以及啟用變更日誌檢查點的 RocksDB 狀態儲存庫。支援 Databricks 執行環境 15.4 LTS 及以上版本。有效值：非負整數。
`snapshotPartitionId`	None	若指定，查詢僅讀取此分割區。必須與一起 `snapshotStartBatchId`指定。無法使用 `readChangeFeed`。支援 Databricks 執行環境 15.4 LTS 及以上版本。有效值：非負整數。
`readChangeFeed`	`false`	當 `true`時，回`changeStartBatchIdchangeEndBatchId`傳在指定批次範圍內的狀態變化。需要 `changeStartBatchId`。無法與 `joinSide`、 `batchId`、 `snapshotStartBatchIdsnapshotPartitionId`、或一起使用。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值： `true`， `false`。詳情請參見「閱讀結構化串流狀態變更」。
`changeStartBatchId`	None	變更進料範圍的起始批次 ID。在`readChangeFeed`為`true`時，為必要項。僅在 `readChangeFeed` 設定為 `true`時適用。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值：非負整數。
`changeEndBatchId`	最新批次識別碼	變更資訊流範圍的結束批次 ID。必須大於或等於 `changeStartBatchId`。僅在 `readChangeFeed` 設定為 `true`時適用。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值：非負整數。
`stateVarName`	None	要讀取狀態變數名稱。狀態變數名稱是運算子在`transformWithState`函`StatefulProcessor`數中每個變數`init`的唯一名稱。使用 `transformWithState` 接線員時必須如此。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值：任意字串。
`readRegisteredTimers`	`false`	當 `true`時，讀取操作員使用的 `transformWithState` 註冊計時器。只適用於營運商 `transformWithState` 。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值： `true`， `false`。
`flattenCollectionTypes`	`true`	當 `true`時，會將映射狀態變數和列表狀態變數的紀錄平整化。當 `false`時，會以 Spark SQL `Array` 或 `Map`的形式回傳紀錄。只適用於營運商 `transformWithState` 。支援 Databricks 執行環境 16.4 LTS 及以上版本。有效值： `true`， `false`。

簡訊

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

XML

鑰匙	預設值	Description
`rowTag`	None	要將 XML 檔案中的行標籤視為資料列。在範例 XML `<books> <book><book>...<books>` 中，適當的值為 `book`。這是必要選項。
`samplingRatio`	`1.0`	定義用於推斷資料模式的資料列分數比例。 XML 內建函數會略過此選項。有效值： `0.0` 到 `1.0`。
`excludeAttribute`	`false`	是否要排除元素中的屬性。
`mode`	None	在解析時處理損毀記錄的方式。 `PERMISSIVE`：對於損毀的記錄，將格式錯誤的字串放入由 `columnNameOfCorruptRecord` 設定的欄位中，並將格式錯誤的欄位設定為 `null`。若要保留損毀的記錄，您可以在使用者定義的結構描述中設定名為 `string` 的 `columnNameOfCorruptRecord` 類型欄位。如果方案中沒有該欄位，解析過程中會捨棄損壞的記錄。推斷結構描述時，剖析器會隱含地在輸出結構描述中新增 `columnNameOfCorruptRecord` 欄位。 `DROPMALFORMED`：略過損毀的記錄。 XML 內建函數不支援此模式。 `FAILFAST`：當解析器遇到損毀的記錄時，拋出例外。
`inferSchema`	`true`	如果為 `true`，則嘗試推斷每個產生的 DataFrame 資料行的適當類型。如果為 `false`，則所有產生的資料行都是 `string` 類型。 XML 內建函數會略過此選項。
`columnNameOfCorruptRecord`	`spark.sql.columnNameOfCorruptRecord`	允許重新命名包含由模式建立 `PERMISSIVE` 的錯誤字串的新欄位。
`attributePrefix`	None	屬性的前置詞，用於區分屬性與元素。這將是欄位名稱的前置詞。預設值為 `_`。讀取 XML 時可以為空，但寫入時不能為空。也適用於 DataFrameWriter 的 XML 選項。
`valueTag`	`_VALUE`	此標籤用於元素內的字元資料，而這些元素同時包含屬性或子元素。使用者可以在結構描述中指定 `valueTag` 欄位，或者當字元資料存在於具有其他元素或屬性的元素中時，該欄位將在結構描述推斷期間自動新增。也適用於 DataFrameWriter 的 XML 選項。
`encoding`	`UTF-8`	讀取時，依指定的編碼類型解碼 XML 檔案。對於寫入，請指定已儲存 XML 檔案的編碼 (字元集)。 XML 內建函數會略過此選項。也適用於 DataFrameWriter 的 XML 選項。
`ignoreSurroundingSpaces`	`true`	是否必須跳過包圍數值的空白區域。僅由空白字元組成的字元資料會被忽略。
`rowValidationXSDPath`	None	用於逐列驗證 XML 的選擇性 XSD 檔案路徑。無法驗證的列會被視為解析錯誤。 XSD 不會影響結構本身，無論是提供或推斷。
`ignoreNamespace`	`false`	如果 `true`為，則會忽略 XML 元素和屬性上的命名空間前置詞。例如，標籤 `<abc:author>` 和 `<def:author>` 視為兩者都只是 `<author>`。 `rowTag` 元素上的命名空間無法被忽略，只有其可讀取的子元素才能被略過。即使在 `false` 的情況下，XML 剖析仍不識別命名空間。
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	遵循日期時間模式格式的自定義時間戳格式字串。這適用於 `timestamp` 類型。也適用於 DataFrameWriter 的 XML 選項。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	遵循日期時間模式格式的不含時區的自訂時間標記格式字串。這適用於 TimestampNTZType 類型。也適用於 DataFrameWriter 的 XML 選項。
`dateFormat`	`yyyy-MM-dd`	遵循日期時間模式格式的自訂日期格式字串。這適用於日期類型。也適用於 DataFrameWriter 的 XML 選項。
`locale`	`en-US`	將地區語言標籤設為 IETF BCP 47 格式。例如，在剖析日期和時間戳記時使用 `locale`。
`nullValue`	字串 `null`	設定 null 值的字串表示法。當這是 `null` 時，剖析器不會為欄位寫入屬性和元素。也適用於 DataFrameWriter 的 XML 選項。
`readerCaseSensitive`	`true`	在啟用 rescuedDataColumn 時，指定區分大小寫的行為。若屬實，則救出與結構中名稱不同的資料欄位。若錯誤，則以不區分大小寫的方式讀取資料。
`rescuedDataColumn`	None	是否要將所有因數據類型不符和結構不符（包括欄位大小寫）而無法解析的數據，收集到一個獨立的欄位。使用自動載入器時，系統會預設包含這個欄位。如需詳細資料，請參閱什麼是復原數據欄位？。 `COPY INTO` （舊版）不支援已獲救的數據行，因為您無法使用 `COPY INTO`手動設定架構。 Databricks 建議針對大部分的擷取案例使用自動載入器。
`singleVariantColumn`	`none`	指定單一變體資料列的名稱。若指定此選項用於讀取，則將整個 XML 記錄解析成一個單一的 Variant 欄位，欄位名稱為指定的選項字串值。如果提供此選項來寫入，請將單一 Variant 資料行的值寫入 XML 檔案。也適用於 DataFrameWriter 的 XML 選項。
`useLegacyXMLParser`	`true`	是否要使用舊有的 XML 解析器。舊有解析器對格式錯誤內容的驗證較不嚴格，但記憶體效率較低。設定為 `false` 以選擇更嚴格的預設解析器。
`wildcardColName`	`xs_any`	欄位名稱用於擷取與通配符`xs:any`（）結構元素相符的 XML 元素。不能與 `rescuedDataColumn`一起使用。

DataStreamReader 選項

利用這些選項 DataStreamReader.option() 來設定來自 Delta Lake 表格及其他檔案來源的串流讀取。

關於檔案格式選項（JSON、CSV、Parquet 等），請參見 DataFrameReader 選項。

關於自動裝載機（cloudFiles.*）選項，請參見自動裝填機。

Example

以下範例設定 maxFilesPerTrigger 為三角 10 洲湖表溪流：

Python

df = spark.readStream.format("delta").option("maxFilesPerTrigger", 10).load("/path/to/delta-table")

Scala

val df = spark.readStream.format("delta").option("maxFilesPerTrigger", "10").load("/path/to/delta-table")

常見

以下選項適用於 Delta Lake 表格及其他基於檔案的串流來源。

鑰匙	預設值	Description
`cleanSource`	`off`	如何在串流處理完原始檔案後處理這些檔案。有效值： `off` （無動作）、 `delete` （永久刪除原始檔案）、 `archive` （移至 `sourceArchiveDir`）。當設定為 `archive`時， `sourceArchiveDir` 也必須設定。不適用於 Delta Lake 桌上串流。
`fileNameOnly`	`false`	是否僅以檔名而非完整路徑來識別已處理過的檔案。當 `true`時，位於相同檔名的不同路徑檔案會被視為同一檔案，不會被重新處理。不適用於 Delta Lake 桌上串流。
`latestFirst`	`false`	是否應該先處理每個微批次中最近修改的檔案。當你想盡快處理最新資料時，這很有用。當 `true` 和 `maxFilesPerTriggermaxBytesPerTrigger` 是設定時， `maxFileAge` 則忽略。不適用於 Delta Lake 桌上串流。
`maxBytesPerTrigger`	None	軟最大值則代表每個微批次處理的資料量。若最小輸入單位超過該限制，批次處理量可能超過限制。與一起使用 `maxFilesPerTrigger`時，微批次會處理資料直到先達到任一極限。有效值：正整數。對於自動載入器，改用 `cloudFiles.maxBytesPerTrigger` 即可。參見通用語。
`maxCachedFiles`	`10000`	後續微批次可快取的最大未處理檔案數量。設定 `0` 為關閉快取。當來源目錄包含每個觸發器有許多新檔案時，將此值提高。不適用於 Delta Lake 桌上串流。有效值：正整數或 `0`。
`maxFileAge`	`7d`	考慮處理檔案的最大年齡，相對於最近修改檔案的時間戳記，而非當前系統時間。超過此門檻的檔案會被忽略。接受持續時間字串，例如 `7d` 或 `4h`。什麼時候被忽略 `latestFirst` ， `truemaxFilesPerTriggermaxBytesPerTrigger` 什麼時候被設定。不適用於 Delta Lake 桌上串流。
`maxFilesPerTrigger`	`1000` 為三角洲湖和自動裝填機。其他基於檔案的來源則沒有上限。	每個微批次處理新檔案數量的上限。與一起使用 `maxBytesPerTrigger`時，微批次會處理資料直到先達到任一極限。有效值：正整數。對於自動載入器，改用 `cloudFiles.maxFilesPerTrigger` 即可。參見通用語。
`sourceArchiveDir`	None	當 `cleanSource` 設定為 `archive`時，導向歸檔目錄的路徑。處理後，原始檔案會被移至此路徑，並保留其相對的目錄結構。不適用於 Delta Lake 桌上串流。

自動裝填機

利用這些選項搭配 cloudFiles 來源設定自動載入器，以便從雲端儲存串流擷取。針對來源的選項 cloudFiles 會以作為 cloudFiles 前綴，以保持它們與其他結構化串流來源選項不同的命名空間。

常見

鑰匙	預設值	Description
`cloudFiles.allowOverwrites`	`false`	是否允許輸入目錄檔案變更以覆寫現有的資料。如需設定注意事項，請參閱自動載入器是否會在檔案附加或覆寫時再次處理檔案？
`cloudFiles.backfillInterval`	None	自動載入器可以觸發指定間隔的異步回填。例如 `1 day` ，每日回填或 `1 week` 每周回填。如需詳細資訊，請參閱使用 cloudFiles.backfillInterval 觸發一般回填。當`cloudFiles.useManagedFileEvents`設定為`true`時，請勿使用。
`cloudFiles.cleanSource`	`OFF`	是否要從輸入目錄自動刪除已處理的檔案。當設定為 `OFF` [預設值] 時，不會刪除任何檔案。當設定為 `DELETE`時，自動載入器會在處理檔案 30 天后自動刪除檔案。若要這樣做，自動載入器必須具有來源目錄的寫入許可權。當設定為 `MOVE`時，自動載入器會在處理檔案後 30 天內自動將檔案移至指定的位置 `cloudFiles.cleanSource.moveDestination` 。若要這樣做，自動載入器必須具有來源目錄以及移動位置的寫入許可權。當檔案在表格值函式的結果`commit_time`中具有非空值`cloud_files_state`時，該檔案即被視為處理中。請參閱 `cloud_files_state` 資料表值函式。處理後的額外 30 天等待可透過 `cloudFiles.cleanSource.retentionDuration`進行設定。啟用 `cloudFiles.cleanSource`前請先檢視以下考量事項：如果有多個串流同時消耗來源位置的資料，Azure Databricks 不建議使用此選項，因為最快的使用者會刪除檔案，且較慢的來源不會被匯入。啟用此功能需自動載入器在檢查點維持額外狀態，這會增加效能負擔，但透過表值函數提升可觀察性 `cloud_files_state` 。請參閱 `cloud_files_state` 資料表值函式。 `cleanSource`使用目前的設定來決定是否要執行或`MOVEDELETE`指定檔案。例如，假設在檔案原本處理時設定是 `MOVE`，但在30天後檔案變成清除候選專案時，設定變更為 `DELETE`。在此情況下，cleanSource 將會刪除檔案。檔案並不保證一過期 `retentionDuration` 就能被清理。為了降低成本，自動載入器會與串流處理同時刪除檔案，並在串流處理完成或終止時立即終止。原本可清理但無法在串流處理時清理的檔案，會在下次執行自動載入器時被選取。可在 Databricks 執行環境 16.4 及以上版本中取得。
`cloudFiles.cleanSource.retentionDuration`	`30 days`	處理後的文件成為封存候選對象前需要等待的時間量，使用 `cleanSource`。必須大於 7 天對於 `DELETE`。沒有最低限制 `MOVE`. 該值為 CalendarInterval 字串。例如、`"14 days"`、 `"30 days""2 weeks"`或 `"1 month"`。可在 Databricks 執行環境 16.4 及以上版本中取得。
`cloudFiles.cleanSource.moveDestination`	None	當 `cloudFiles.cleanSource` 設定為 `MOVE` 時，歸檔已處理檔案的路徑。這可以是雲端儲存路徑或 Unity 目錄卷的路徑（例如， `/Volumes/my_catalog/my_schema/my_volume/archive/`）。移動地點必須：不要成為來源目錄的子目錄。如果你把移動目的地放在來源目錄裡，已壓縮的檔案會被重新擷取。請與來源安裝在同一個外部位置、磁碟區或 DBFS 掛載裝置。跨桶與跨容器移動不被支援，會導致錯誤。自動載入器必須具有此目錄的寫入許可權。可在 Databricks 執行環境 16.4 及以上版本中取得。
`cloudFiles.format`	無（必須選項）	來源路徑中的資料檔案格式。有效值包括： `avro`： Avro 檔案 `binaryFile`：二進位檔 `csv`： CSV 檔案 `json`： JSON 檔案 `orc`： ORC 檔案 `parquet`： Parquet 檔案 `text`： TXT 檔案 `xml`： XML 檔案
`cloudFiles.includeExistingFiles`	`true`	是包含串流處理輸入路徑中的現有檔案，還是僅處理初始設定後到達的新檔案。僅在您第一次啟動串流時會評估此選項。在重新啟動串流後變更此選項沒有任何作用。
`cloudFiles.inferColumnTypes`	`false`	在使用結構描述進行推斷時，是否要推斷精確的資料行類型。根據預設，在推斷 JSON 和 CSV 資料集時，資料行會推斷為字串。如需詳細資料，請參閱結構描述推斷。
`cloudFiles.maxBytesPerTrigger`	None	每個觸發程序中要處理的新位元組數目上限。您可以指定位元組字串 (例如 `10g`)，將每個微批次限制為 10 GB 資料。這是軟性上限。如果每個檔案為 3 GB，則 Azure Databricks 在一個微批次中可以處理 12 GB。與 `cloudFiles.maxFilesPerTrigger` 一起使用時，Azure Databricks 將消耗至 `cloudFiles.maxFilesPerTrigger` 或 `cloudFiles.maxBytesPerTrigger` 的較低限度（以先達到者為準）。與 `Trigger.Once()` (`Trigger.Once()` 已取代) 一起使用時，此選項沒有任何作用。在 Databricks Runtime 18.0 及以上版本中，此選項是動態設定，無需手動設定。
`cloudFiles.maxFileAge`	None	為去重目的而追蹤檔案事件的時間長度。 Databricks 不建議調整此參數，除非您正在以每小時數百萬個檔案的速度匯入資料。如需詳細資訊，請參閱檔案事件追蹤一節。過於激進地調整 `cloudFiles.maxFileAge` 可能會導致資料品質問題，例如重複擷取或遺漏檔案。因此，Databricks 建議為 `cloudFiles.maxFileAge` 使用保守設定，例如 90 天，這與類似資料擷取解決方案建議的值相當。
`cloudFiles.maxFilesPerTrigger`	`1000`	每個觸發程序中要處理的新檔案數目上限。與 `cloudFiles.maxBytesPerTrigger` 一起使用時，Azure Databricks 將消耗至 `cloudFiles.maxFilesPerTrigger` 或 `cloudFiles.maxBytesPerTrigger` 的較低限度（以先達到者為準）。與 `Trigger.Once()` (已取代) 一起使用時，此選項沒有任何作用。在 Databricks Runtime 18.0 及以上版本中，此選項是動態設定，無需手動設定。
`cloudFiles.partitionColumns`	None	一份逗號分隔的 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`	`addNewColumns` 當未提供結構時， `none` 否則	在資料中發現新欄位時，模式用於結構演進。根據預設，在推斷 JSON 資料集時，資料行會推斷為字串。如需詳細資訊，請參閱架構演進。
`cloudFiles.schemaHints`	None	您在結構描述推斷期間提供給自動載入器的結構描述資訊。如需詳細資料，請參閱結構描述提示。
`cloudFiles.schemaLocation`	無（推斷結構所需）	儲存推斷結構描述和後續變更的位置。如需詳細資料，請參閱結構描述推斷。
`cloudFiles.useStrictGlobber`	`false`	是否要使用與 Apache Spark 中其他檔案來源的預設通配行為一致的嚴格通配器。如需詳細資料，請參閱常見資料載入模式。在 Databricks Runtime 12.2 LTS 和更新版本中可用。
`cloudFiles.validateOptions`	`true`	是否要驗證 Auto Loader 的選項，並對未知或不一致的選項返回錯誤。

目錄列表

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

檔案通知

關於設定檔案通知模式的資訊，包括必要的雲端權限、設定說明及認證方法，請參閱「在檔案通知模式下設定自動載入器串流」。

鑰匙	預設值	Description
`cloudFiles.fetchParallelism`	`1`	從佇列服務擷取訊息時要使用的執行緒數目。當`cloudFiles.useManagedFileEvents`設定為`true`時，請勿使用。
`cloudFiles.pathRewrites`	None	只有在你指定 a `queueUrl` 會接收來自多個 S3 桶的檔案通知，並且你想使用設定用於存取這些容器資料的掛載點時才必要。使用此選項可使用掛載點重新寫入 `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`	None	一系列索引鍵/值標籤組，可協助關聯和識別相關資源，例如： `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`	`false`	當設定為 `true`時，自動載入器會使用檔案事件服務來探索外部位置中的檔案。只有在載入路徑位於已啟用檔案事件的外部位置時，才可以使用此選項。請參閱檔案事件搭配檔案通知模式的使用方法。檔案事件在檔案發現上提供通知等級的效能，因為自動載入器可以在最後一次執行後發現新檔案。不同於目錄清單，此程式不需要列出目錄中的所有檔案。有些情況下，即使已啟用檔案事件選項，自動載入器仍會使用目錄清單：在初始載入期間的自動載入器，當`includeExistingFiles`設定為`true`時，會進行完整目錄列舉，以探索自動載入器啟動之前存在於目錄中的所有檔案。檔案事件服務會快取最近建立的檔案，以優化檔案探索。如果自動載入器不常執行，此快取可能會過期，而自動載入器會回復到目錄清單，以探索檔案並更新快取。若要避免這種情況，請至少每隔七天叫用自動載入器一次。請參閱「何時自動載入器在檔案事件中使用目錄列表？」，以完整列出自動載入器使用此選項使用目錄列表的情況。支援 Databricks Runtime 14.3 LTS 及以上版本。
`cloudFiles.listOnStart`	`false`	當設定為 `true`時，自動載入器會在串流開始時執行完整目錄列表，而非從檢查點的續寫標記開始。使用此選項來恢復錯誤，例如 `CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN`。請參見我如何從錯誤中恢復`CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN`？
`cloudFiles.useNotifications`	`false`	是否使用檔案通知模式來確定何時存在新檔案。如果為 `false`，則使用目錄清單模式。請參閱比較自動載入器檔案偵測模式。當`cloudFiles.useManagedFileEvents`設定為`true`時，請勿使用。

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

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

Databricks 保留這些鍵名，且無法覆寫它們的值。

雲端專屬

自動載入器提供設定雲端基礎設施以設定檔案通知模式的選項。關於所需的雲端權限與設定說明，請參閱「在檔案通知模式下設定自動載入器串流」。

AWS

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

鑰匙	預設值	Description
`cloudFiles.region`	EC2 實例的區域	來源 S3 儲存桶所在的區域，以及你想建立 AWS SNS 和 SQS 服務的地方。

鑰匙	預設值	Description
`cloudFiles.restrictNotificationSetupToSameAWSAccountId`	`false`	僅允許來自與 SNS 主題相同帳戶中的 AWS S3 儲存桶的事件通知。如果設定為 true，「Auto Loader」只會接受來自與 SNS 主題位於相同帳戶中的 AWS S3 收集桶的事件通知。當 `false` 時，存取政策不會限制跨帳戶的儲存桶和 SNS 主題設定。當 SNS 主題和儲存桶路徑與不同帳戶相關聯時，這很有用。適用於 Databricks Runtime 17.2 和更新版本。

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

鑰匙	預設值	Description
`cloudFiles.queueUrl`	None	SQS 佇列的 URL。如果提供此選項，則自動載入器會直接取用此佇列中的事件，而不是設定自己的 AWS SNS 和 SQS 服務。

AWS 認證選項

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

鑰匙	預設值	Description
`databricks.serviceCredential`	None	Databricks 服務認證的名稱。適用於 Databricks Runtime 16.1 和更新版本。

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

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

Azure

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

鑰匙	預設值	Description
`cloudFiles.resourceGroup`	None	儲存帳號建立的 Azure 資源群組。
`cloudFiles.subscriptionId`	None	建立資源群組的 Azure 訂閱 ID。
`databricks.serviceCredential`	None	Databricks 服務認證的名稱。適用於 Databricks Runtime 16.1 和更新版本。

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

鑰匙	預設值	Description
`cloudFiles.clientId`	None	服務主體的用戶端識別碼或應用程式識別碼。
`cloudFiles.clientSecret`	None	服務主體的用戶端密鑰。
`cloudFiles.connectionString`	None	儲存體帳戶的連接字串，基於帳戶存取金鑰或共用存取簽章 (SAS)。
`cloudFiles.tenantId`	None	建立服務主體的 Azure 租戶 ID。

只有在你設定 cloudFiles.useNotifications = true 並希望自動載入器使用現有佇列時，才提供以下選項：

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

GCP

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

鑰匙	預設值	Description
`cloudFiles.projectId`	None	GCS 桶所在的專案 ID。 Google Cloud Pub/Sub 訂閱也是在此專案中建立的。
`databricks.serviceCredential`	None	Databricks 服務認證的名稱。適用於 Databricks Runtime 16.1 和更新版本。

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

鑰匙	預設值	Description
`cloudFiles.client`	None	Google 服務帳戶的用戶端識別碼。
`cloudFiles.clientEmail`	None	Google 服務帳戶的電子郵件。
`cloudFiles.privateKey`	None	針對Google服務帳戶產生的私鑰。
`cloudFiles.privateKeyId`	None	針對Google服務帳戶產生的私鑰標識碼。

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

鑰匙	預設值	Description
`cloudFiles.subscription`	None	Google Cloud Pub/Sub 訂用帳戶的名稱。如果提供此選項，則雲端檔案來源將取用此佇列中的事件，而不是設定自身的 GCS 通知和 Google Cloud Pub/Sub 服務。

三角洲湖

當使用 spark.readStreamDelta Lake 表格讀取時，以下選項適用。

鑰匙	預設值	Description
`allowSourceColumnDrop`	None	設定為 Delta 表格版本號，或 `"always"` 允許串流在從來源資料表架構中刪除欄位後繼續。設定為版本號時，會確認該版本之前的所有結構變更。需要 `schemaTrackingLocation`。請參閱使用 Delta Lake 欄位映射重新命名和刪除欄位。
`allowSourceColumnRename`	None	設定為 Delta 表格版本號，或 `"always"` 允許串流在來源資料表中欄位重新命名後繼續。設定為版本號時，會確認該版本之前的所有結構變更。需要 `schemaTrackingLocation`。請參閱使用 Delta Lake 欄位映射重新命名和刪除欄位。
`allowSourceColumnTypeChange`	None	設定為 Delta 表格版本號，或 `"always"` 允許串流在來源資料表中欄位類型變更後繼續。設定為版本號時，會確認該版本之前的所有結構變更。需要 `schemaTrackingLocation`。請參閱類型擴展。
`excludeRegex`	None	正則表達式模式。路徑與模式相符的檔案會被排除在串流讀取之外。有助於過濾不符合預期命名慣例的檔案。
`failOnDataLoss`	`true`	如果來源資料因日誌保留而被刪除，串流查詢是否會失敗（`logRetentionDuration`）。設定為 `false` 跳過遺失資料並繼續處理。請參閱設定時光旅行查詢中的資料保留政策。
`ignoreChanges` (已取代)	`false`	支援 Databricks Runtime 11.3 LTS 及以下版本。在修改操作 `UPDATE`如、 `MERGE INTO`、 `DELETE`或 `OVERWRITE`後重新發布重寫資料檔案。未變更的列可能會與新列同時發出，因此下游消費者必須處理重複的。刪除作業不會同步到下游。在 Databricks Runtime 12.2 LTS 及以上版本中被取代 `skipChangeCommits` 。
`ignoreDeletes` (已取代)	`false`	忽略在分割區邊界刪除資料的交易（僅完整分割區丟棄）。不處理非分割區的刪除、更新或其他修改。請改用 `skipChangeCommits`。
`readChangeFeed` 或 `readChangeData`	`false`	是否啟用串流查詢時讀取變更資料流。啟用時，串流會發出列級變更（插入、更新與刪除），並附加額外的元資料欄位。請參閱在 Azure Databricks 上使用 Delta Lake 變更數據饋送。
`schemaTrackingLocation`	None	路徑指向一個目錄，Delta Lake 會追蹤串流讀取的結構變更。當從啟用欄位映射的表格串流並使用 `allowSourceColumn*` 選項處理結構演化時，這是必須的。必須在 `checkpointLocation` 串流查詢範圍內。請參閱使用 Delta Lake 欄位映射重新命名和刪除欄位。
`skipChangeCommits`	`false`	忽略刪除或修改現有紀錄的交易，程序僅附加。 Databricks 建議大多數不使用變更資料串流的工作負載採用此選項。在 Databricks Runtime 12.2 LTS 和更新版本中可用。參見跳過上游變更提交。`skipChangeCommits`
`startingTimestamp`	最新可得資料	開始閱讀的時間戳記。串流會讀取所有在指定時間戳記時或之後提交的資料表變更。若時間戳記早於所有可用資料表提交，串流則從最早的可用提交開始。不能與 `startingVersion`一起使用。如果串流檢查點已經存在，就忽略了。有效值：時間戳字串如， `"2019-01-01T00:00:00.000Z"` 或日期字串如 `"2019-01-01"`。
`startingVersion`	最新可得資料	可以從 Delta 表格版本開始閱讀。串流讀取所有在指定版本或之後提交的變更。指定 `"latest"` 只從最新的變更開始。不能與 `startingTimestamp`一起使用。如果串流檢查點已經存在，就忽略了。請參見使用表格歷史記錄。
`withEventTimeOrder`	`false`	將初始資料表快照分割成事件時間桶，以防止紀錄被錯誤標記為遲發事件，並在帶有浮水印的有狀態查詢中丟棄。初始快照處理開始後，若不刪除檢查點，則無法更改。在 Databricks Runtime 11.3 LTS 和更新版本中可用。請參閱「處理初始快照而不遺失資料」。

卡夫卡

請將這些選項與以下任一spark.readStream.format("kafka")spark.read.format("kafka")或：

鑰匙	預設值	Description
`assign`	None	具體需要消費的分區。你必須精確指定其中一個 `subscribe`、 `subscribePattern`或 `assign` 選項。有效值：一個 JSON 字串，例如 `{"topicA":[0,1],"topicB":[2,4]}`。
`failOnDataLoss`	`true`	例如，如果資料可能因刪除主題或偏移截斷而遺失，查詢是否失敗。設定為 `false` 跳過遺失資料並繼續。有效值： `true`， `false`。 Databricks 保守估計資料是否可能遺失。然而，這可能會導致誤報。
`fetchoffset.numretries`	`3`	取卡夫卡偏移量時的重試次數失敗。有效值：非負整數。
`fetchoffset.retryintervalms`	`1000`	偏移取回重試之間的間隔（以毫秒計）。有效值：非負整數。
`groupIdPrefix`	`spark-kafka-source` （串流中）， `spark-kafka-relation` （批次）	用於自動產生的 Kafka 消費者群組 ID 的自訂前綴。如果 `kafka.group.id` 是明確設定，連接器會忽略這個選項。有效值：任意字串。
`includeHeaders`	`false`	是否要將 Kafka 訊息標頭作為輸出欄位包含。有效值： `true`， `false`。
`kafkaconsumer.polltimeoutms`	None	Kafka 消費者 `poll()` 通話的逾時時間以毫秒計。有效值：正整數。
`kafka.bootstrap.servers`	None	一份逗號分隔的 Kafka broker host：port 位址清單。設定卡夫卡客戶的 `bootstrap.servers` 屬性。如果你發現沒有來自 Kafka 的資料，請檢查這個經紀商的地址清單是否有錯誤的地址。如果訊息代理程式位址清單不正確，可能沒有任何錯誤。 Kafka 客戶端以為代理最終會可用，當收到網路錯誤時會無限重試。
`maxRecordsPerPartition`	None	每個 Spark 分割區的最大記錄數。設定後，連接器會分割 Kafka 分割區，使每個 Spark 分割區最多讀取此數量的記錄。有效值：正整數。你也可以用這個選項搭配 `minPartitions`。當兩個選項都設定好時，Spark 會使用能產生更多分割區的選項。
`minPartitions`	None	從 Kafka 讀取的 Spark 分割區數量。設定後，連接器會分割大型 Kafka 分割區以增加平行性。未設定時，Spark 會為每個 Kafka 主題分割建立一個分割區。對於處理資料偏移或峰值負載很有用。有效值：正整數。此選項會為每個觸發器重新初始化 Kafka 使用者，可能會影響 SSL 的效能。
`startingOffsets`	`latest` （串流中）， `earliest` （批次）	查詢開始讀取的偏移量。有效值： `earliest`、， `latest`或每個分割區的 JSON 偏移量字串，例如 `{"topicA":{"0":23,"1":-2}}`。在 JSON 字串中，是 `-1` 最新的偏移量。 `-2` 是最早的偏移量。對於串流查詢，這個選項只適用於新查詢開始時。繼續查詢總是使用檢查點。在查詢過程中，新的分割區會從最早的偏移量開始讀取。對於批次查詢， `latest` 則不允許。
`startingOffsetsByTimestamp`	None	每個分割區的起始偏移量清單，以毫秒為單位的時間戳記。當時間戳記不存在偏移量時，查詢行為由決定 `startingOffsetsByTimestampStrategy`。有效值：每個分割區的時間戳記 JSON 字串，例如 `{"topicA":{"0":1000,"1":2000}}`。對於串流查詢，這個選項只適用於新查詢開始時。繼續查詢總是使用檢查點。在查詢過程中，新的分割區會從最早的偏移量開始讀取。
`startingOffsetsByTimestampStrategy`	`error`	當時間戳`startingOffsetsByTimestampstartingTimestamp`記在或中未找到偏移時所採用的策略。有效值： `error` （提出例外）、 `latest` （使用最新可用的偏移量）。
`startingTimestamp`	None	全域起始時間戳（以毫秒計）適用於所有分割區。當時間戳沒有偏移時，行為由控制 `startingOffsetsByTimestampStrategy`。有效值：非負整數。
`subscribe`	None	訂閱主題。你必須精確指定其中一個 `subscribe`、 `subscribePattern`或 `assign` 選項。有效值：一個逗號分隔的主題名稱清單。
`subscribePattern`	None	過去的模式是用來訂閱主題的。你必須精確指定其中一個 `subscribe`、 `subscribePattern`或 `assign` 選項。例如： `topic.*` 。有效值：任何 Java 正則表達式字串。

以下選項僅適用於串流閱讀：spark.readStream.format("kafka")

鑰匙	預設值	Description
`bytesEstimateWindowLength`	`300s`	用來估算該指標剩餘位元組 `estimatedTotalBytesBehindLatest` 的時間窗。有效值：持續時間字串，如 `10m600s`或。請參閱擷取 Kafka 計量。
`maxOffsetsPerTrigger`	None	每個觸發間隔可處理的最大偏移量數。偏移量會按比例分布在主題分割之間。有效值：正整數。
`maxTriggerDelay`	`15m`	觸發前累積的最大等待時間 `minOffsetsPerTrigger` 。有效值：持續時間字串，如 `10m600s`或。
`minOffsetsPerTrigger`	None	觸發微批次前累積的最小偏移量數。當 `maxTriggerDelay` 達到時，微批次仍會執行。有效值：正整數。

關於僅適用於批次讀取的 spark.read.format("kafka")偏移選項，請參見 DataFrameReader Kafka 選項。

關於 Kafka 客戶端（kafka.*）及認證選項，請參見選項。

DataFrameWriter 選項

使用這些選項搭配 DataFrameWriter.option() 和 DataFrameWriterV2.option() 來控制 Azure Databricks 如何寫入資料。

Example

以下範例設定 mergeSchema 為， True 用於撰寫 Delta Lake 表格：

Python

df.write.format("delta").option("mergeSchema", True).saveAsTable("my_table")

Scala

df.write.format("delta").option("mergeSchema", "true").saveAsTable("my_table")

阿弗羅

鑰匙	預設值	Description
`avroSchema`	None	完整的 Avro 架構以 JSON 字串形式呈現。使用此選項將 Spark SQL 類型轉換成特定的 Avro 類型。適用於 Avro 檔案。
`avroSchemaUrl`	None	一個指向 Avro 架構檔案的網址。用來代替 `avroSchema` 結構儲存在外部時。與 `avroSchema`互斥。適用於 Avro 檔案。
`compression`	`snappy`	寫作時使用的壓縮編碼器。有效值：`uncompressed`， `deflate`， `snappy`， `bzip2`， `xzzstandard`，，。適用於 Avro 檔案。
`recordName`	`topLevelRecord`	輸出 Avro 架構中的頂層紀錄名稱。適用於 Avro 檔案。
`positionalFieldMatching`	`false`	是否應該依欄位位置而非名稱，將 Spark 架構與 Avro 架構的欄位匹配。適用於 Avro 檔案。
`recordNamespace`	空字串	輸出 Avro 架構中頂層記錄的命名空間。適用於 Avro 檔案。

三角洲湖與阿帕契冰山

鑰匙	預設值	Description
`clusterByAuto`	`false`	是否啟用自動液體叢集，也就是 Azure Databricks 根據查詢模式選擇叢集欄位。僅在時有效。`mode("overwrite")` 無法搭配 `append` 模式使用。適用於 Databricks Runtime 16.4 和更新版本。適用於使用液體叢集來處理表格。
`mergeSchema`	None	是否要啟用寫入操作的結構演化。來源資料框中的新欄位會被加入目標資料表結構。適用於批次和串流附加。適用於更新表架構。
`overwriteSchema`	None	覆寫時是否要替換資料表結構和分割。需要 `mode("overwrite")` 但沒有 `replaceWhere`。不能與 `partitionOverwriteMode`一起使用。適用於更新表架構。
`partitionOverwriteMode`	None	分割區覆寫模式。將此設定為只 `dynamic` 覆蓋包含新資料的分割區，其他分割區保持不變。舊有模式，不支援無伺服器運算或 Databricks SQL 的使用。有效值： `static`， `dynamic`。適用於使用 Delta Lake 選擇性覆蓋資料。
`replaceOn`	None	一個布林運算式，用來匹配目標資料表中的列，並用來源查詢的列來替換。可以同時參考目標資料表和來源查詢的欄位。目標中與來源列相符的列會被刪除並替換。如果來源是空的，則不會發生刪除。用於 `targetAlias` 辨識欄位引用。支援 Databricks Runtime 17.1 及以上版本。適用於使用 Delta Lake 選擇性覆蓋資料。
`replaceUsing`	None	一個逗號分隔的欄位名稱清單，用於匹配目標資料表與來源查詢之間的列。目標與來源必須包含所有列出的欄位。在等式比較下，目標中與來源列相符的列會被刪除並替換。 `NULL` 數值被視為不相等，且不會相匹配。支援 Databricks 執行環境 16.3 及以上版本。適用於使用 Delta Lake 選擇性覆蓋資料。
`replaceWhere`	None	一個謂語表達。原子層次只覆蓋與謂詞相符的記錄。適用於使用 Delta Lake 選擇性覆蓋資料。
`targetAlias`	None	目標資料表的字串別名。當條件同時參考目標資料表與來源查詢的欄位時，請與`replaceOnreplaceWhere`或用來消除欄位參照的歧義。適用於使用 Delta Lake 選擇性覆蓋資料。
`txnAppId`	None	唯一字串用於識別冪등寫 `foreachBatch` 入操作的應用。使用「 `txnVersion` 共存」以確保能精確一次寫入多個 Delta Lake 資料表。適用於冪등 表格寫入的使用`foreachBatch`。
`txnVersion`	None	作為冪등 `foreachBatch` 運算的事務版本，使用單調遞增的數字。使用「 `txnAppId` 共存」以確保能精確一次寫入多個 Delta Lake 資料表。適用於冪등 表格寫入的使用`foreachBatch`。
`optimizeWrite`	None	是否要啟用自動優化寫入這個寫入操作。覆蓋設定。`spark.databricks.delta.optimizeWrite.enabled` 適用於三角洲湖在Azure Databricks？中是什麼。
`userMetadata`	None	使用者定義的字串附加在寫入操作的提交元資料後。可見於輸出 `DESCRIBE HISTORY`。適用於用自訂元資料豐富表格。

CSV

鑰匙	預設值	Description
`charToEscapeQuoteEscaping`	`\0` （未啟用）	當逃脫字元與引號字元不同時，該字元用於逃離。適用於 csv（DataFrameWriter）。
`compression`	`none`	寫作時使用的壓縮編碼器。有效值：`none`、`bzip2`、`gzip`、`lz4snappydeflatezstd`。適用於 csv（DataFrameWriter）。
`dateFormat`	`yyyy-MM-dd`	格式字串可指定日期欄位值。適用於 csv（DataFrameWriter）。
`emptyValue`	空字串	為空值（非空值）寫字串。適用於 csv（DataFrameWriter）。
`encoding`	`UTF-8`	輸出檔案的字元編碼。適用於 csv（DataFrameWriter）。
`escape`	`\`	用於逃脫引號值的字元。適用於 csv（DataFrameWriter）。
`escapeQuotes`	`true`	是否要跳脫引號字元在引號欄位內。適用於 csv（DataFrameWriter）。
`header`	`false`	是否要將欄位名稱寫在輸出的第一行。適用於 csv（DataFrameWriter）。
`ignoreLeadingWhiteSpace`	`false`	是否在撰寫時要從數值中刪除前導空白。適用於 csv（DataFrameWriter）。
`ignoreTrailingWhiteSpace`	`false`	寫字時是否要刪除數值後的空白。適用於 csv（DataFrameWriter）。
`lineSep`	`\n`	唱片間使用的行分隔符串。適用於 csv（DataFrameWriter）。
`locale`	`en-US`	`java.util.Locale` 識別碼。影響寫作時日期與時間戳記值的格式。
`nullValue`	空字串	字串是為 null 值所寫的。適用於 csv（DataFrameWriter）。
`quote`	`"`	用來引用包含分隔符欄位值的字元。適用於 csv（DataFrameWriter）。
`quoteAll`	`false`	是否要以引號包覆所有欄位值，不論內容如何。適用於 csv（DataFrameWriter）。
`sep`	`,`	欄位分隔符字元。適用於 csv（DataFrameWriter）。
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	時間戳記欄位值的格式字串。適用於 csv（DataFrameWriter）。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	格式化字串時，時間戳記時區不加欄位`TimestampNTZType`值（）。

Excel

鑰匙	預設值	Description
`dataAddress`	None	寫入的起始格子是工作表名稱或起始格子。若省略，則寫入一個從格`A1`子開始的`Sheet1`表。接受一個圖紙名稱（）`"SheetName"`或單一單元參考（`"SheetName!A1"`）。寫入不支援儲存格範圍。
`dateFormatInWrite`	`yyyy-mm-dd`	Excel儲存格格式字串套用於`Date`欄位。採用 Excel 格式語法。
`headerRows`	`0`	是否要把欄位名稱寫在第一列。有效值： `0`， `1`。
`timestampNTZFormat`	`yyyy-mm-dd hh:mm:ss`	Excel儲存格格式字串套用於`TimestampNTZ` 和 `Timestamp` 欄位。採用 Excel 格式語法。
`version`	`xlsx`	Excel 檔案格式版本用於撰寫。有效值： `xlsx`， `xls`。

JSON

鑰匙	預設值	Description
`compression`	`none`	寫作時使用的壓縮編碼器。有效值：`none`、`bzip2`、`gzip`、`lz4snappydeflatezstd`。適用於 json（DataFrameWriter）。
`dateFormat`	`yyyy-MM-dd`	格式字串可指定日期欄位值。適用於 json（DataFrameWriter）。
`encoding`	`UTF-8`	輸出檔案的字元編碼。適用於 json（DataFrameWriter）。
`ignoreNullFields`	值 `spark.sql.jsonGenerator.ignoreNullFields`	是否應該從 JSON 輸出中省略 null 值的欄位。適用於 json（DataFrameWriter）。
`lineSep`	`\n`	唱片間使用的行分隔符串。適用於 json（DataFrameWriter）。
`locale`	`en-US`	`java.util.Locale` 識別碼。影響寫作時日期與時間戳記值的格式。
`pretty`	`false`	是否啟用漂亮的（縮排、多行）JSON 輸出。
`sortKeys`	`false`	是否要在輸出中按字母順序排序 JSON 物件的鍵。對產生確定性輸出非常有用。
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	時間戳記欄位值的格式字串。適用於 json（DataFrameWriter）。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	格式化字串時，時間戳記時區不加欄位`TimestampNTZType`值（）。
`writeNonAsciiCharacterAsCodePoint`	`false`	是否將非 ASCII 字元編碼為 `\uXXXX` Unicode 跳脫序列，而非直接輸出 UTF-8 字元。

奧爾克

鑰匙	預設值	Description
`compression`	`zstd`	寫作時使用的壓縮編碼器。有效值：`none`， `uncompressed`， `snappy`， `zliblzo`， `zstdlz4`，。 `brotli` 適用於獸人（DataFrameWriter）。

拼花地板

鑰匙	預設值	Description
`compression`	`snappy`	寫作時使用的壓縮編碼器。有效值：`none`， `uncompressed`， `snappy`， `gziplzo`，， `brotli`， `lz4`，， `lz4_raw`，。 `zstd` 適用於 parquet（DataFrameWriter）。
`spark.sql.parquet.outputTimestampType`	`INT96`	用於編碼時間戳記欄位的實體型態。有效值： `INT96`， `TIMESTAMP_MICROS`， `TIMESTAMP_MILLIS`。 `INT96`用於相容於不支援標準時間戳記類型的舊有 Parquet 讀取器。

簡訊

鑰匙	預設值	Description
`compression`	`none`	寫作時使用的壓縮編碼器。有效值：`none`、`bzip2`、`gzip`、`lz4snappydeflatezstd`。適用於文字（DataFrameWriter）。
`encoding`	`UTF-8`	輸出檔案的字元編碼。
`lineSep`	`\n`	唱片間使用的行分隔符串。適用於文字（DataFrameWriter）。

XML

鑰匙	預設值	Description
`arrayElementName`	`item`	元素名稱用於沒有明確名稱的陣列元素。適用於 xml（DataFrameWriter）。
`attributePrefix`	`_`	前綴會加在對應 XML 屬性的欄位名稱前。適用於 xml（DataFrameWriter）。
`compression`	`none`	寫作時使用的壓縮編碼器。有效值：`none`、`bzip2`、`gzip`、`lz4snappydeflatezstd`。適用於 xml（DataFrameWriter）。
`dateFormat`	`yyyy-MM-dd`	格式字串可指定日期欄位值。適用於 xml（DataFrameWriter）。
`declaration`	`version="1.0" encoding="UTF-8" standalone="yes"`	每個輸出檔案頂端寫入的 XML 宣告字串。設為空字串以抑制宣告。適用於 xml（DataFrameWriter）。
`encoding`	`UTF-8`	輸出檔案的字元編碼。適用於 xml（DataFrameWriter）。
`indent`	4格	字串用於縮排輸出中的子元素。設定為空字串以關閉縮排，並將每一列寫在一行上。
`locale`	`en-US`	`java.util.Locale` 識別碼。影響寫作時日期與時間戳記值的格式。
`nullValue`	`null`	為 null 值所寫的字串。當設定為 `null`時，空欄位的屬性與子元素會被省略。適用於 xml（DataFrameWriter）。
`rootTag`	`ROWS`	根元素標籤，將所有列元素包裹在輸出中。適用於 xml（DataFrameWriter）。
`rowTag`	`ROW`	代表輸出中一列的元素標籤。適用於 xml（DataFrameWriter）。
`singleVariantColumn`	None	用來寫入 XML 檔案的單一 Variant 欄位名稱。適用於 xml（DataFrameWriter）。
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	時間戳記欄位值的格式字串。適用於 xml（DataFrameWriter）。
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	格式化字串以包含時間戳記，但不包含時區欄位值。適用於 xml（DataFrameWriter）。
`validateName`	`true`	如果欄位名稱不是有效的 XML 元素識別碼，是否要拋出例外。適用於 xml（DataFrameWriter）。
`valueTag`	`_VALUE`	欄位名稱用於同時具有屬性或子元素的 XML 元素中的字元資料。適用於 xml（DataFrameWriter）。

DataStreamWriter 的選項

使用這些選項 DataStreamWriter.option() 來設定串流寫入。

Example

以下範例設定了溪流的檢查點位置：

Python

(df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table"))

Scala

df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table")

常見

鑰匙	預設值	Description
`checkpointLocation`	無（必修）	串流查詢的檢查點目錄路徑。這是容錯性及精確一次處理保證所必需的。每個串流查詢必須使用獨特的檢查點位置。 Databricks 建議將檢查點存放在 Unity 目錄卷或雲端儲存路徑中。請參閱結構化串流檢查點。
`path`	None	為像 Parquet 這類檔案型串流匯流器的輸出路徑。僅適用於檔案格式。

控制台水槽

鑰匙	預設值	Description
`numRows`	`20`	寫入主控台匯入槽時，每個微批次要顯示的列數。
`truncate`	`true`	顯示列時是否要截斷長字串。設定為以 `false` 顯示完整字串值。

三角洲湖

當使用 format("delta")Delta Lake 表格寫入溪流時，以下選項適用。僅覆蓋的選項如 overwriteSchema、 replaceWhere和 partitionOverwriteMode 不支援串流寫入。

鑰匙	預設值	Description
`mergeSchema`	`false`	當串流資料框架包含新欄位時，是否要演進 Delta Lake 資料表結構。僅適用於附加輸出模式。適用於更新表架構。
`userMetadata`	None	使用者定義的字串附加在寫入操作的提交元資料後。可見於輸出 `DESCRIBE HISTORY`。適用於用自訂元資料豐富表格。

檔案匯

以下選項適用於將串流寫成基於檔案的格式（Parquet、JSON、CSV、ORC、文字）。關於格式特定的選項，請參見 DataFrameWriter 選項。

鑰匙	預設值	Description
`retention`	None	用於容錯與壓縮的匯入中繼資料檔案保存多久。接受時間字串，例如 `7 days24 hours`或。未設定時，元資料檔案會被永久保留。

卡夫卡沉沒式

關於寫入串流給 Kafka 的完整選項清單，請參見選項。

鑰匙	預設值	Description
`kafka.bootstrap.servers`	None	Required. 一份逗號分隔的 Kafka 經紀 `host:port` 人地址清單。
`topic`	None	所有排的目標卡夫卡主題。若資料框架未包含 `topic` 欄位，則為必要。
`kafka.*`	None	任何以 `kafka.`為前綴的 Kafka 製作人配置。例如： `kafka.compression.type` 。

記憶匯

鑰匙	預設值	Description
`queryName`	無（必修）	查詢所寫入的記憶體資料表名稱。記憶匯聚器必備。也可以透過 `.queryName()`.
`mode`	`exactlyonce`	記憶體匯入的交付保證。 `exactlyonce` 使用微批次模式，語意精確為一次。 `atleastonce` 使用至少一次語意的連續模式。有效值： `exactlyonce`， `atleastonce`。

火花功能選項

部分 Spark SQL 內建函式接受 options 一個控制解析或序列化行為的映射。 Pass 選項可以選成 Python dict 或 Scala Map[String, String]。

Example

以下範例解析 JSON 欄位，同時丟棄格式錯誤的記錄：

Python

from pyspark.sql.functions import from_json
from pyspark.sql.types import StructType, StructField, StringType

schema = StructType([StructField("name", StringType())])
df = df.withColumn("parsed", from_json("json_col", schema, {"mode": "DROPMALFORMED"}))

Scala

import org.apache.spark.sql.functions.from_json
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("name", StringType)))
val df = df.withColumn("parsed", from_json(col("json_col"), schema, Map("mode" -> "DROPMALFORMED")))

阿弗羅

Avro 函式接受與對應 DataFrame 選項相同的選項：

from_avro 並 schema_of_avro 使用 DataFrameReader 的 Avro 選項。
to_avro 使用 DataFrameWriter的Avro選項。

Example

以下範例解碼了啟用結構演化的 Avro 欄位：

Python

from pyspark.sql.functions import from_avro

df = df.withColumn("decoded", from_avro("avro_col", json_schema, {"avroSchemaEvolutionMode": "restart"}))

Scala

import org.apache.spark.sql.avro.functions.from_avro

val df = df.withColumn("decoded", from_avro(col("avro_col"), jsonSchema, Map("avroSchemaEvolutionMode" -> "restart")))

此外，結構to_avro登錄檔的變體from_avro及接受以下選項：

鑰匙	預設值	Description
`schemaId`	None	用於解碼 Avro 資料時使用的 Confluent Schema Registry 的結構 ID，該資料編碼的結構與不相容 `jsonFormatSchema`。僅適用於。`from_avro`
`confluent.schema.registry.*`	None	Confluent Schema Registry 用戶端配置屬性。使用此前綴傳遞任何 Confluent SR 用戶端屬性，例如 `confluent.schema.registry.basic.auth.user.info` 基本的認證憑證。對於結構登錄檔的變體 `from_avro` 和 `to_avro`。

CSV

CSV 函式接受與對應 DataFrame 選項相同的選項：

from_csv 並 schema_of_csv 使用 DataFrameReader 的 CSV 選項。
to_csv 使用 DataFrameWriter的CSV選項。

Example

以下範例是用自訂分隔符和 NULL 值來讀 CSV：

Python

from pyspark.sql.functions import from_csv
from pyspark.sql.types import StructType, StructField, IntegerType, StringType

schema = StructType([StructField("id", IntegerType()), StructField("name", StringType())])
df = df.withColumn("parsed", from_csv("csv_col", schema, {"sep": "|", "nullValue": "N/A"}))

Scala

import org.apache.spark.sql.functions.from_csv
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("id", IntegerType), StructField("name", StringType)))
val df = df.withColumn("parsed", from_csv(col("csv_col"), schema, Map("sep" -> "|", "nullValue" -> "N/A")))

JSON

JSON 函式接受與對應 DataFrame 選項相同的選項：

from_json 並 schema_of_json 使用 DataFrameReader 的 JSON 選項。
to_json 使用 DataFrameWriter 的 JSON 選項。

Example

以下範例是寫入 JSON 時，欄位 NULL 被忽略並啟用漂亮格式：

Python

from pyspark.sql.functions import to_json

df = df.withColumn("json_str", to_json("struct_col", {"pretty": "true", "ignoreNullFields": "true"}))

Scala

import org.apache.spark.sql.functions.to_json

val df = df.withColumn("json_str", to_json(col("struct_col"), Map("pretty" -> "true", "ignoreNullFields" -> "true")))

普羅托布夫

from_protobuf 且 to_protobuf 不使用基於檔案的資料來源。 Protobuf 資料總是以這些函式以二進位欄位讀寫。選擇權以「a Map[String, String] 」方式傳遞，且大小寫區分。

Example

以下範例是使用 PERMISSIVE 模式解碼 Protobuf 欄位：

Python

from pyspark.sql.functions import from_protobuf

df = df.withColumn("decoded", from_protobuf("proto_col", "MyMessage", "/path/to/descriptor.desc",
    {"mode": "PERMISSIVE", "enums.as.ints": "true"}))

Scala

import org.apache.spark.sql.protobuf.functions.from_protobuf

val df = df.withColumn("decoded", from_protobuf(col("proto_col"), "MyMessage", "/path/to/descriptor.desc",
    Map("mode" -> "PERMISSIVE", "enums.as.ints" -> "true")))

Protobuf 函式使用以下選項：

鑰匙	預設值	Description
`mode`	`FAILFAST`	如何處理腐敗的紀錄。 `FAILFAST` 引發異常。 `PERMISSIVE` 將malformed欄位設為null。有效值： `FAILFAST`， `PERMISSIVE`。適用於 `from_protobuf`。
`recursive.fields.max.depth`	`-1` （禁用）	遞迴 Protobuf 場的最大遞迴深度。設定為 `0` 關閉遞迴場支援。有效值： `0` 到 `10`。適用於 `from_protobuf`。
`convert.any.fields.to.json`	`false`	是否要將 Protobuf `Any` 欄位轉換成 JSON 字串，而不是 `STRUCT`. 適用於 `from_protobuf`。
`emit.default.values`	`false`	是否要輸出欄位為零或預設值（proto3語意）。當 `false`時，預設值欄位會從輸出中省略。適用於 `from_protobuf`。
`enums.as.ints`	`false`	是否要將列舉欄位渲染成整數值而非字串。適用於 `from_protobuf`。
`upcast.unsigned.ints`	`false`	是否要上階 `uint32` 到 `Long` 以及 `uint64` 防止 `Decimal(20,0)` 整數溢位。適用於 `from_protobuf`。
`unwrap.primitive.wrapper.types`	`false`	是否要將包裝型別（例如 `Int32Value` 和 `StringValue`）展開`google.protobuf`為對應的原始 Spark 型態。適用於 `from_protobuf`。
`retain.empty.message.types`	`false`	是否透過插入虛擬欄位，在輸出結構中保留空的 Protobuf 訊息類型。適用於 `from_protobuf`。
`schema.registry.subject`	None	圖式登錄主體名稱。使用和 `to_protobuf`的結構登錄版本`from_protobuf`時必須。
`schema.registry.address`	None	結構登錄位址（主機與埠）。使用和 `to_protobuf`的結構登錄版本`from_protobuf`時必須。
`schema.registry.protobuf.name`	None	當結構登錄主體包含多個訊息時，指定使用哪一則 Protobuf 訊息。 Optional.

XML

XML 函式接受與對應 DataFrame 選項相同的選項：

from_xml 並 schema_of_xml 使用 DataFrameReader 的 XML 選項。
to_xml 使用 DataFrameWriter的XML選項。

Example

以下範例是用自訂根標籤和列標籤來撰寫 XML：

Python

from pyspark.sql.functions import to_xml

df = df.withColumn("xml_str", to_xml("struct_col", {"rootTag": "records", "rowTag": "record"}))

Scala

import org.apache.spark.sql.functions.to_xml

val df = df.withColumn("xml_str", to_xml(col("struct_col"), Map("rootTag" -> "records", "rowTag" -> "record")))

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-01