Função com valor de tabela list_files

Aplica-se a:check marked yes Databricks SQL check marked yes Databricks Runtime 18 LTS and above

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

Retorna a lista de arquivos em um caminho, incluindo uma FILE referência para cada arquivo.

Sintaxe

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

Arguments

  • path: Um STRING caminho a listar. Pode ser um caminho de volume, um caminho de localização externo ou um caminho em outro sistema de armazenamento de arquivos, como SFTP, SharePoint ou Google Drive.
  • connection: Uma conexão opcional do Unity Catalog usada para autenticação com sistemas como SFTP, SharePoint ou Google Drive.
  • recursive: Um opcional BOOLEAN que controla se a função desce para subdiretórios. Os valores aceitos são:
    • true: Lista arquivos no caminho e em todos os seus subdiretórios, e não retorna diretórios. Este é o valor padrão.
    • false: Lista apenas as entradas imediatas do caminho e retorna diretórios com uma nullfile referência e um size de 0.

Os connection argumentos e recursive devem ser passados pelo nome usando => sintaxe, por exemplo connection => my_conn.

Returns

Uma tabela com uma linha por arquivo, com as seguintes colunas:

Coluna Tipo Description
path STRING O caminho para o arquivo.
size BIGINT O tamanho do arquivo, em bytes.
modification_time TIMESTAMP O tempo da última modificação do arquivo, em UTC.
file FILE Uma referência ao arquivo.

Condições de erro comuns

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

Para mais informações, veja Condições de erro no Azure Databricks.

Examples

Para listar os arquivos em um diretório de volume:

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

A função retorna uma linha por arquivo:

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

Para listar arquivos de um sistema externo usando uma conexão com o Unity Catalog:

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

Para listar apenas as entradas imediatas de um diretório, defina recursive para false:

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

Diretórios aparecem nos resultados com uma nullfile referência e um size de 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

Para calcular o tamanho total de todos os arquivos em um diretório, soma a size coluna. Como recursive o padrão é true, isso inclui arquivos em subdiretórios:

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

A consulta retorna o tamanho combinado em bytes:

total_bytes
1234
  • Last updated on