Aller au contenu principal
Dernière mise à jour le

list_files table-valued function

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 18 LTS and above

Beta

This feature is in Beta.

Returns the list of files at a path, including a FILE reference for each file.

Syntax​

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

Arguments​

  • path: A STRING path to list. Can be a volume path, an external location path, or a path on another file storage system such as SFTP, SharePoint, or Google Drive.
  • connection: An optional Unity Catalog connection used to authenticate with systems such as SFTP, SharePoint, or Google Drive.
  • recursive: An optional BOOLEAN that controls whether the function descends into subdirectories. Accepted values are:
    • true: Lists files in the path and all of its subdirectories, and doesn't return directories. This is the default value.
    • false: Lists only the immediate entries of the path, and returns directories with a null file reference and a size of 0.

The connection and recursive arguments must be passed by name using => syntax, for example connection => my_conn.

Returns​

A table with one row per file, with the following columns:

Column

Type

Description

path

STRING

The path to the file.

size

BIGINT

The size of the file, in bytes.

modification_time

TIMESTAMP

The last modification time of the file, in UTC.

file

FILE

A reference to the file.

Column

Type

Description

path

STRING

The path to the file.

size

BIGINT

The size of the file, in bytes.

modification_time

TIMESTAMP

The last modification time of the file, in UTC.

file

FILE

A reference to the file.

Common error conditions​

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

For more information, see Error conditions in Databricks.

Examples​

To list the files in a volume directory:

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

The function returns one row per file:

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

To list files from an external system using a Unity Catalog connection:

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

To list only the immediate entries of a directory, set recursive to false:

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

Directories appear in the results with a null file reference and a size of 0:

Text
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

To compute the total size of all files in a directory, sum the size column. Because recursive defaults to true, this includes files in subdirectories:

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

The query returns the combined size in bytes:

Text
total_bytes
1234
Sur cette page