read_files table-valued 函式

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

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

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

語法

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

引數

此函式需要 選項索引鍵的具名參數調用 。

• pathSTRING：具有資料位置 URI 的 。 支援從 Azure Data Lake Storage Gen2 （'abfss://'）、S3 （s3://） 和 Google Cloud Storage （'gs://'） 讀取。 可以包含 Glob。 如需詳細資訊，請參閱 檔案探索 。
• option_key：要設定的選項名稱。 您需要針對包含點 （） 的選項使用反引號 （.'）。
• option_value：要設定選項的常數表達式。 接受常值和純量函式。

傳回

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

檔案探索

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

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

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

read_files 在探索具有 glob 的檔案時，會使用自動載入器嚴格的 Globber。 此選項已設定 useStrictGlobber 。 停用嚴格的 globber 時，會捨棄尾端斜線 （/） 和星形圖樣，例如 /*/ 可以展開至探索多個目錄。 請參閱下列範例，以查看行為的差異。

結構描述推斷

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

schemaHints選項可用來修正推斷架構的子集。 如需詳細資訊，請參閱使用架構提示覆寫架構推斷。

預設會提供 ， rescuedDataColumn 以營救不符合架構的任何數據。 如需詳細資訊，請參閱什麼是獲救的數據行？ 您可以藉由設定 選項schemaEvolutionMode => 'none'來卸載 rescuedDataColumn 。

數據分割架構推斷

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 選項
• 串流選項

基本選項

泛型選項

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

JSON 選項

CSV 選項

XML 選項

PARQUET 選項

AVRO 選項

BINARYFILE 選項

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

TEXT 選項

ORC 選項

串流選項

這些選項適用於在串流數據表或串流查詢內使用read_files時。

範例

-- 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);

相關文章

• 建立串流資料表
• read_kafka 資料表值函式