read_files 資料表值函式

適用於： Databricks SQL Databricks Runtime 13.3 LTS 和更新版本

讀取所提供位置下的檔案，並以表格式格式傳回數據。

支援讀取 JSON、CSV、XML、、TEXTBINARYFILEPARQUET、、、AVRO和 ORC 檔案格式。 可以自動偵測檔格式，並推斷所有檔案的統一架構。

語法

read_files(path [, option_key => option_value ] [...])

引數

此函式需要使用具名參數來呼叫選項鍵。

• path：具有資料位置 URI 的STRING物件。 支援從 Azure Data Lake Storage（'abfss://'）、S3（s3://）和 Google Cloud Storage（'gs://'） 讀取。 可以包含通配符。 如需詳細資訊，請參閱 檔案探索 。
• option_key：要設定的選項名稱。 您需要使用反引號（`) for options that contain dots (`）。
• option_value：要設定選項的常數表達式。 接受常值和純量函式。

退貨

數據表，其中包含在指定 path底下讀取之檔案的數據。

檔案搜尋

read_files 可以讀取個別檔案或讀取所提供目錄下的檔案。 read_files會以遞歸方式探索所提供目錄下的所有檔案，除非提供了glob，指示read_files遞歸至特定的目錄模式。

使用 Glob 模式篩選目錄或檔案

Glob 模式可用於在路徑中提供時篩選目錄和檔案。

圖案	描述
?	匹配任何單一字元
*	比對零或多個字符
[abc]	比對字元集 {a，b，c} 的單一字元。
[a-z]	比對字元範圍 {a...z} 中的單一字元。
[^a]	匹配不屬於字元集或範圍 {a} 的單一字元。 請注意， ^ 字元必須緊接在左括弧右邊。
{ab,cd}	比對字串集 {ab， cd} 中的字串。
{ab,c{de, fh}}	比對字串集 {ab， cde， cfh} 中的字串。

read_files 使用 Auto Loader 的嚴格 globber 來探索具有 glob 的檔案。 這是由 useStrictGlobber 選項設定的。 停用嚴格的 globber 時，尾端斜線（/）會被捨棄，像 /*/ 這樣的星號圖案可以擴展為探索多個目錄。 請參閱下列範例，以查看行為的差異。

圖案	檔案路徑	已停用 Strict globber	已啟用 Strict globber
/a/b	/a/b/c/file.txt	是	是
/a/b	/a/b_dir/c/file.txt	否	否
/a/b	/a/b.txt	否	否
/a/b/	/a/b.txt	否	否
/a/*/c/	/a/b/c/file.txt	是	是
/a/*/c/	/a/b/c/d/file.txt	是	是
/a/*/d/	/a/b/c/d/file.txt	是	否
/a/*/c/	/a/b/x/y/c/file.txt	是	否
/a/*/c	/a/b/c_file.txt	是	否
/a/*/c/	/a/b/c_file.txt	是	否
/a/*/c	/a/b/cookie/file.txt	是	否
/a/b*	/a/b.txt	是	是
/a/b*	/a/b/file.txt	是	是
/a/{0.txt,1.txt}	/a/0.txt	是	是
/a/*/{0.txt,1.txt}	/a/0.txt	否	否
/a/b/[cde-h]/i/	/a/b/c/i/file.txt	是	是

架構推斷

您可以使用read_files選項明確提供schema檔案的架構。 未提供架構時，read_files 會嘗試在探索到的檔案中推斷一個統一的架構，除非使用 LIMIT 語句，否則需要讀取所有檔案。 即使使用 LIMIT 查詢，可能也會讀取比所需的更大的檔案集，以傳回更代表性的數據架構。 如果使用者未提供查詢語句，Databricks 會在筆記本和 SQL 編輯器中自動新增 LIMIT 語句以供 SELECT 查詢使用。

schemaHints選項可用來修正推斷架構的子集。 請參閱 使用架構提示覆寫架構推斷 以獲取更多詳細資訊。

預設會提供rescuedDataColumn，以救援任何不符合架構的數據。 如需詳細資訊，請參閱何謂被救出的資料欄？ 您可以透過設定選項rescuedDataColumn來省略schemaEvolutionMode => 'none'。

數據分割架構推斷

read_files還可以推斷分割欄位，如果檔案儲存在遵循Hive樣式的分割目錄下，即/column_name=column_value/。 如果提供schema，則新的分區列將使用schema中提供的型別。 如果分區欄位不屬於提供的 schema，則會忽略推斷的分區欄位。

如果某欄位同時存在於分區架構和數據欄位中，則會使用從分區值讀取的值，而不是數據值。 如果您想要忽略來自資料目錄的值並使用資料欄位，您可以使用 partitionColumns 選項，以逗號分隔的格式提供分割欄位列表。

partitionColumns選項也可以用來指示read_files要在最終推斷的模式中包含哪些已發現的欄。 提供空字串會忽略所有分區欄位。

也可以提供 schemaHints 選項來覆寫分區列所推斷的架構。

TEXT和 BINARYFILE 格式具有固定的架構，但也read_files會儘可能嘗試推斷這些格式的數據分割。

串流資料表中的使用方式

read_files 可用於串流數據表，將檔案內嵌至 Delta Lake。 read_files 在串流數據表查詢中使用時，會利用自動載入器。 您必須使用 STREAM 關鍵詞搭配 read_files。 如需詳細資訊，請參閱什麼是自動載入器？

在串流查詢中使用時， read_files 會使用數據的範例來推斷架構，並在處理更多數據時演進架構。 如需詳細資訊，請參閱 在自動載入器 中設定架構推斷和演進。

選項。

• 基本選項
• 泛型選項
• JSON 選項
• CSV 選項
• XML 選項
• PARQUET 選項
• AVRO 選項
• BINARYFILE 選項
• TEXT 選項
• ORC 選項
• 串流選項

基本選項

選項
format 類型:String 來源路徑中的資料檔案格式。 如果未提供，則自動推斷。 允許的值包括： avro：Avro 檔案 binaryFile：二進位檔 csv：讀取 CSV 檔案 json：JSON 檔案 orc：ORC 檔案 parquet：使用 Azure Databricks 讀取 Parquet 檔案 text：文字檔 xml：讀取和寫入 XML 檔案 預設值：無
inferColumnTypes 類型:Boolean 在利用模式推斷時，是否推斷精確的資料行類型。 預設情況下，推斷 JSON 和 CSV 資料集時會推斷欄位。 如需詳細資料，請參閱結構描述推斷。 請注意，這與自動載入器的默認相反。 預設值：true
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。 預設值：無
schemaHints 類型:String 您在結構描述推斷期間提供給自動載入器的結構描述資訊。 如需詳細資料，請參閱結構描述提示。 預設值：無
useStrictGlobber 類型:Boolean 是否要使用與 Apache Spark 中其他檔案來源的預設通配行為一致的嚴格通配器。 如需詳細資料，請參閱常見資料載入模式。 在 Databricks Runtime 12.2 LTS 和更新版本中可用。 請注意，這與自動載入器的默認相反。 預設值：true

泛型選項

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

選項
ignoreCorruptFiles 類型:Boolean 是否要略過損毀的檔案。 如果為 true，則 Spark 作業會在遇到損毀的檔案時繼續執行，而且仍然會傳回已讀取的內容。 可觀察為 numSkippedCorruptFiles，如中所示 Delta Lake 歷程記錄的 operationMetrics 欄位。 在 Databricks Runtime 11.3 LTS 和更新版本中可用。 預設值：false
ignoreMissingFiles 類型:Boolean 是否略過遺漏的檔案。 如果為 true，則 Spark 作業會在遇到遺漏的檔案時繼續執行，而且仍然會傳回已讀取的內容。 在 Databricks Runtime 11.3 LTS 和更新版本中可用。 預設值：Auto Loader 為 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 字串包含未轉義的控制字符（值小於 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。 當 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]，並拋出錯誤訊息，因為它找不到結尾引號。 如果逸出 '\' 的字元定義為 '\'，則會以 2 個值讀取記錄：[a\] 和 [b]。 預設值：'\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 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 是否將因資料類型不符和結構描述不符（包括欄位大小寫）而無法解析的所有資料收集至單獨欄位。 使用自動載入程式時，此欄位會預設包含在內。 如需詳細資料，請參閱什麼是復原的資料行？。 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 選項

選項	描述	範圍
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 建議針對大部分的擷取案例使用自動載入器。 預設值：無。	閱讀

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。 預設值：UTF-8
lineSep 類型:String 兩筆連續 TEXT 記錄之間的字串。 預設值：無，其中涵蓋 \r、\r\n 和 \n
wholeText 類型:Boolean 是否要將檔案讀取為單一記錄。 預設值：false

ORC 選項

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

串流選項

在串流數據表或者串流查詢中使用read_files時，這些選項適用。

選項
allowOverwrites 類型:Boolean 是否要重新處理探索後已修改的檔案。 在若檔案自上次成功刷新查詢開始時間以來有任何修改，則在刷新期間將處理該檔案的最新可用版本。 預設值：false
includeExistingFiles 類型:Boolean 是包含串流處理輸入路徑中的現有檔案，還是僅處理初始設定後到達的新檔案。 僅在您第一次啟動串流時會評估此選項。 在重新啟動串流後變更此選項沒有任何作用。 預設值：true
maxBytesPerTrigger 類型:Byte String 每個觸發程序中要處理的新位元組數目上限。 您可以指定位元組字串 (例如 10g)，將每個微批次限制為 10 GB 資料。 這是柔性最大值。 如果每個檔案為 3 GB，則 Azure Databricks 在一個微批次中可以處理 12 GB。 與 maxFilesPerTrigger 一起使用時，Azure Databricks 將消耗至 maxFilesPerTrigger 或 maxBytesPerTrigger 的較低限度（以先達到者為準）。 注意：對於在無伺服器 SQL 倉儲上建立的串流數據表，此選項 maxFilesPerTrigger 不應設定為利用動態許可控制，這會依工作負載大小和無伺服器計算資源進行調整，以提供最佳的延遲和效能。 預設值：無
maxFilesPerTrigger 類型:Integer 每個觸發程序中要處理的新檔案數目上限。 與 maxBytesPerTrigger 一起使用時，Azure Databricks 將消耗至 maxFilesPerTrigger 或 maxBytesPerTrigger 的較低限度（以先達到者為準）。 注意：對於在無伺服器 SQL 倉儲上建立的串流數據表，此選項 maxBytesPerTrigger 不應設定為利用動態許可控制，這會依工作負載大小和無伺服器計算資源進行調整，以提供最佳的延遲和效能。 預設值：1000
schemaEvolutionMode 類型:String 在資料中發現新欄位時，模式用於結構演進。 根據預設，在推斷 JSON 資料集時，資料行會推斷為字串。 如需詳細資料，請參閱結構描述演進。 此選項不適用於 text 和 binaryFile 檔案。 預設值：未提供結構描述時為 "addNewColumns"。 否則為 "none"。
schemaLocation 類型:String 儲存推斷結構描述和後續變更的位置。 如需詳細資料，請參閱結構描述推斷。 在串流數據表查詢中使用時，不需要架構位置。 預設值：無

範例

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);

相關文章

• CREATE STREAMING TABLE
• read_kafka 數據表值函式