list_files 表值函数

适用于：检查标记为“是”的 Databricks SQL 检查标记为“是”是 Databricks Runtime 18 LTS 及更高版本

Important

此功能在 Beta 版中。 工作区管理员可以从 预览 页控制对此功能的访问。 请参阅 Manage 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 Catalog连接从外部系统中列出文件：

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

目录出现在结果中，参考文献和asize为nullfile0：

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