list_files função que retorna um valor de tabela

Aplica-se a:assinalado Databricks SQL assinalado sim Databricks Runtime 18 LTS e superiores

Importante

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

Devolve a lista de ficheiros num caminho, incluindo uma FILE referência para cada ficheiro.

Syntax

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 noutro sistema de armazenamento de ficheiros como SFTP, SharePoint ou Google Drive.
  • connection: Uma ligação opcional ao 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 aceites são:
    • true: Lista ficheiros no caminho e em todos os seus subdiretórios, e não devolve diretórios. Este é o valor padrão.
    • false: Lista apenas as entradas imediatas do caminho e devolve 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.

Devoluções

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

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

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 ficheiros num diretório de volumes:

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

A função devolve uma linha por ficheiro:

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 ficheiros de um sistema externo usando uma ligação ao 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);

Os 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 ficheiros num diretório, soma a size coluna. Como recursive por defeito é true, isto inclui ficheiros em subdiretórios:

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

A consulta devolve o tamanho combinado em bytes:

total_bytes
1234
  • Last updated on