`read_files` 資料表值函式

適用於： 標記為「是」 Databricks SQL Databricks Runtime 13.3 LTS 和更新版本

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

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

Note

提供 Beta 版本，設定 format => 'file' 為每個檔案回 FILE 傳參考資料，而非讀取檔案內容。請參考 FILE FILE 類型 type 與 Ingest 檔案。

語法

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檔案下讀取資料的資料表。結構依檔案格式而定：

BINARYFILE：回傳固定結構：

資料行	類型	描述
`path`	`STRING`	檔案的完整路徑。
`modificationTime`	`TIMESTAMP`	檔案最後修改時間。
`length`	`LONG`	檔案的大小 (以位元組為單位)。
`content`	`BINARY`	檔案的二進位內容。查詢檔案元資料時，請使用 `* EXCEPT (content)` 以排除二進位內容。

TEXT：回傳一個固定的結構，僅有一個valueSTRING（）欄位。
所有其他格式（JSON、CSV、XML、PARQUET、AVRO、ORC）：架構可從檔案內容推斷，或透過 schema 選項明確提供。

`_metadata` 柱狀

read_files 會 _metadata 暴露一個包含檔案層元資料的欄位。此欄位不包含在 SELECT * 結果中，必須明確選擇。包含以下欄位：

領域	類型	描述
`file_path`	`STRING`	來源檔案的完整路徑。
`file_name`	`STRING`	來源檔案的名稱。
`file_size`	`LONG`	以位元組為單位的來源檔案大小。
`file_modification_time`	`TIMESTAMP`	原始檔案的最後修改時間。
`file_block_start`	`LONG`	讀取檔案區塊的起始點。
`file_block_length`	`LONG`	讀取檔案區塊的長度。

要包含 _metadata 在結果中，請明確選擇：

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

檔案搜尋

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 在探索具有 glob 的檔案時，會使用自動載入器嚴格的 Globber。這是由 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 讀取 Unity Catalog 外部位置或 Unity 目錄卷（包括管理與外部）的檔案。你必須擁有 READ FILES 外部位置或 READ VOLUME 包含你想讀取檔案的磁碟區的權限。請參考使用 Unity 目錄連接雲端物件儲存或 Unity 目錄卷的定義。

串流資料表中的使用方式

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

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

基本選項

選項	類型	描述	預設值
`format`	`String`	來源路徑中的資料檔案格式。若省略，則為自動推斷。允許的值包括、、（Beta）、 `avro`、 `binaryFile`、 `csvfilejson`和。 `orcparquettextxml`	沒有
`schema`	`String`	要讀取檔案的架構。例如，請使用 DDL 格式 `'id int, ts timestamp, event string'`指定一個結構字串。若省略，則 `read_files` 嘗試在發現的檔案間推斷出統一的結構結構。	沒有
`inferColumnTypes`	`Boolean`	在利用模式推斷時，是否推斷精確的資料行類型。預設情況下，推斷 JSON 和 CSV 資料集時會推斷欄位。這和自動載入器的預設行為相反。參見範疇推論。	`true`
`partitionColumns`	`String`	一份逗號分隔的 Hive 風格分割欄清單，可從檔案的目錄結構推斷。蜂巢式分割欄是由等號組合的鍵值對，例如 `<base-path>/a=x/b=1/c=y/file.format`。在此範例中，分割欄位為 `a`、`b` 和 `c`。如果你使用 schema 推論並從 to load 資料傳遞 `<base-path>` ，這些欄位會自動加入你的 schema。如果你指定一個結構，自動載入器會預期這些欄位會包含在結構中。如果你不希望這些欄位成為結構的一部分，請指定 `""` 忽略它們。你也可以用這個選項從複雜目錄結構中的檔案路徑推斷欄位。例如，以下檔案中，將`cloudFiles.partitionColumns`返回`year,month,day`指定為 `year=2022` ，`file1.csv`但 `month` 和 `day` 欄位為 `null`。 `month` 且 `day` 被正確解析為 `file2.csv` 和 `file3.csv`： `<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`	沒有
`schemaHints`	`String`	在結構推論時傳遞給自動載入器的結構資訊。如需詳細資料，請參閱結構描述提示。	沒有
`useStrictGlobber`	`Boolean`	是否要使用與 Apache Spark 中其他檔案來源的預設通配行為一致的嚴格通配器。如需詳細資料，請參閱常見資料載入模式。在 Databricks Runtime 12.2 LTS 和更新版本中可用。這和自動載入器的預設設定相反。	`true`

格式專屬選項

關於每種檔案格式（JSON、CSV、XML、Parquet、Avro、文字、ORC及二進位）的專屬選項，請參閱 DataFrameReader 選項。

串流選項

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

選項	類型	描述	預設值
`allowOverwrites`	`Boolean`	是否要重新處理發現後變更的檔案。在重新整理時，如果檔案在最後一次成功刷新後被修改，則會 `read_files` 重新處理。	`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);

非結構化檔案的工作

以下範例利用 BINARYFILE 格式來讀取與篩選儲存在 Unity 目錄卷中的非結構化檔案，並結合 read_files AI 功能處理檔案內容。

列出卷中所有檔案：使用 * EXCEPT (content) 以返回檔案中繼資料而不載入二進位內容，並明確選擇 _metadata 包含檔案層級的中繼資料欄位。

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>',
  format => 'binaryFile'
);

依尺寸篩選的影像檔案：可針對 fileNamePattern 特定影像檔案類型進行篩選，並篩選 _metadata.file_size 以只回傳指定大小範圍內的檔案。

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

列出過去一天內修改的 PDF 檔案：使用 fileNamePattern 以鎖定 PDF 檔案並 modificationTime 篩選，只回放過去一天內變更的檔案。

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,PDF}'
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

對影像檔案執行 AI 功能：用 ai_query 來處理從雲端儲存路徑讀取的影像檔案。在欄位上篩選 _metadata 以鎖定特定檔案。

SELECT
  path AS file_path,
  ai_query(
    'system.ai.llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

解析與檔名模式相符的文件：用於 ai_parse_document 從 PDF 和圖片中擷取結構化內容。依篩選 _metadata.file_name 以鎖定特定檔案。

SELECT
  path AS file_path,
  ai_parse_document(
    content,
    map('version', '2.0')
  ) AS result
FROM read_files(
  '/Volumes/main/public/my_files/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';

將檔案與結構化資料表合併：非結構化工作流程通常需要將儲存在資料表中的結構化資料與非結構化檔案合併。以下範例以兩個結構化資料表將檔案串連於雲端儲存路徑，並依檔案大小與使用者屬性進行篩選。與 user_files 的連接是透過使用 split 和 element_at從檔案路徑中擷取檔案 ID 來完成的。

SELECT
  users.user_id,
  user_files.file_id,
  files._metadata.file_name AS file_name,
  files.* EXCEPT (content),
  ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
  's3://my-bucket-name/files/',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
  ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
  ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
  AND files._metadata.file_size < 10000000;

list_files 數據表值函式

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-11