list_files 資料表值函式

適用於：勾選標記為是 Databricks SQL 勾選 Databricks 執行時間 18 LTS 及以上

Important

這項功能位於 測試版 (Beta) 中。 工作區管理員可以從 「預覽 」頁面控制對此功能的存取。 請參閱 管理 Azure Databricks 預覽。

回傳路徑上的檔案清單，包含 FILE 每個檔案的參考。

Syntax

list_files(path [, connection => connection ] [, recursive => recursive ])

Arguments

  • path：一條 STRING 通往清單的路徑。 可以是卷路徑、外部位置路徑，或是其他檔案儲存系統（如 SFTP、SharePoint 或 Google Drive）上的路徑。
  • connection：一個可選的 Unity Catalog 連線，用於與 SFTP、SharePoint 或 Google Drive 等系統進行驗證。
  • recursive： 一個可選 BOOLEAN 的選項，用來控制函式是否會下降到子目錄。 公認的數值如下：
    • true： 列出路徑及其所有子目錄中的檔案，且不回傳目錄。 這是預設值。
    • false： 僅列出路徑的直接條目，並回傳帶有參考 nullfile 和 a size 的 0目錄。

connection recursive參數必須以=>語法（例如connection => my_conn）以名稱傳遞。

Returns

一個每個檔案一列的表格，欄位如下：

資料行 類型 Description
path STRING 檔案的路徑。
size BIGINT 檔案大小，以位元組為單位。
modification_time TIMESTAMP 檔案最後修改時間，UTC。
file FILE 這是對檔案的參考。

常見錯誤條件

  • LIST_FILES_AUTHORIZATION_ERROR.ON_PATH
  • LIST_FILES_AUTHORIZATION_ERROR.ON_CONNECTION
  • LIST_FILES_ERROR.PATH_NOT_EXISTS
  • LIST_FILES_ERROR.CONNECTION_NOT_EXISTS

欲了解更多資訊，請參閱 Azure Databricks 中的錯誤條件。

Examples

要在卷目錄中列出檔案：

SELECT * FROM list_files('/Volumes/my_catalog/my_schema/my_volume/');

函式每個檔案回傳一列：

path                                                 size   modification_time         file
/Volumes/my_catalog/my_schema/my_volume/file1.json   1234   2026-04-11 00:00:00.000   <file>

要透過 Unity 目錄連線從外部系統中列出檔案：

SELECT path, size FROM list_files('https://drive.google.com/drive/folders/my-folder-id', connection => my_gdrive_connection);

若要只列出目錄的直接條目，請設 recursive 為 false：

SELECT * FROM list_files('/Volumes/my_catalog/my_schema/my_volume/', recursive => false);

目錄會出現在結果中，參考文獻為 null和 a filesize：0

path                                                 size   modification_time         file
/Volumes/my_catalog/my_schema/my_volume/file1.json   1234   2026-04-11 00:00:00.000   <file>
/Volumes/my_catalog/my_schema/my_volume/subdir/      0      2026-04-11 00:00:00.000   NULL

要計算目錄中所有檔案的總大小，請將欄位加總 size 。 由於 recursive 預設為 true，這包括子目錄中的檔案：

SELECT sum(size) AS total_bytes FROM list_files('/Volumes/my_catalog/my_schema/my_volume/');

查詢會回傳合併大小（位元組）：

total_bytes
1234
  • Last updated on