Função com valor de tabela read_files

Aplica-se a: SQL do Databricks Databricks Runtime 13.3 LTS e versões posteriores

Lê arquivos em um local fornecido e retorna os dados em forma de tabela.

Suporta leitura JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO, e ORC formatos de arquivo. Pode detectar o formato de arquivo automaticamente e inferir um esquema unificado em todos os arquivos.

Sintaxe

read_files(path [, option_key => option_value ] [...])

Argumentos

Essa função requer invocação de parâmetro nomeada para as chaves de opção.

• path: um STRING com o URI do local dos dados. Dá suporte à leitura de Azure Data Lake Storage ('abfss://'), S3 (s3://) e Google Cloud Storage ('gs://'). Pode conter globs. Consulte Descoberta de arquivos para obter mais detalhes.
• option_key: o nome da opção a ser configurada. Você precisa usar backticks () for options that contain dots (.').
• option_value: uma expressão constante para a qual definir a opção. Aceita literais e funções escalares.

Retorna

Uma tabela que contém os dados de arquivos lidos sob o determinado path. O esquema depende do formato do arquivo:

• BINARYFILE: retorna um esquema fixo:

  Coluna	Tipo	Descrição
  path	STRING	O caminho completo para o arquivo.
  modificationTime	TIMESTAMP	A hora da última modificação do arquivo.
  length	LONG	O tamanho do arquivo em bytes.
  content	BINARY	O conteúdo binário do arquivo. Use * EXCEPT (content) para excluir conteúdo binário ao consultar metadados de arquivo.

• TEXT: retorna um esquema fixo com uma única value coluna (STRING).

• Todos os outros formatos (JSON, CSV, XML, PARQUET, AVRO, ORC): o esquema é inferido do conteúdo do arquivo ou fornecido explicitamente usando a opção schema .

_metadata Coluna

read_files expõe uma _metadata coluna com metadados no nível do arquivo. Esta coluna não está incluída nos SELECT * resultados e deve ser selecionada explicitamente. Ela contém os seguintes campos:

Para incluir _metadata nos resultados, selecione-o explicitamente:

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

Descoberta de arquivos

read_files pode ler um arquivo individual ou ler arquivos em um diretório fornecido. read_files descobre todos os arquivos no diretório fornecido recursivamente, a menos que um glob seja fornecido, o que instrui read_files a recursar em um padrão de diretório específico.

Filtrando diretórios ou arquivos usando padrões glob

Padrões glob podem ser usados para filtrar diretórios e arquivos quando fornecidos no caminho.

read_files usa o globber estrito do Carregador Automático ao descobrir arquivos com globs. Isso é configurado pela opção useStrictGlobber. Quando o globber estrito está desabilitado, as barras à direita (/) são descartadas e um padrão de star como /*/ pode se expandir para descobrir vários diretórios. Veja os exemplos abaixo para ver a diferença de comportamento.

Inferência de esquema

O esquema dos arquivos pode ser fornecido explicitamente read_files com a opção schema. Quando o esquema não é fornecido, read_files tenta inferir um esquema unificado entre os arquivos descobertos, o que requer a leitura de todos os arquivos, a menos que uma instrução LIMIT seja usada. Mesmo ao usar uma consulta LIMIT, um conjunto maior de arquivos do que o necessário pode ser lido para retornar um esquema mais representativo dos dados. Databricks adiciona automaticamente uma LIMIT instrução para SELECT consultas em notebooks e no editor de SQL caso um usuário não tenha fornecido uma.

A opção schemaHints pode ser usada para corrigir subconjuntos do esquema inferido. Consulte Substituir a inferência de esquema com dicas de esquema para obter mais detalhes.

Um rescuedDataColumn é fornecido por padrão para resgatar os dados que não correspondem ao esquema. Confira Qual é a coluna de dados resgatados? para obter mais detalhes. Você pode remover o rescuedDataColumn definindo a opção schemaEvolutionMode => 'none'.

Inferência de esquema de partição

read_files também pode inferir colunas de particionamento se os arquivos forem armazenados em diretórios particionados no estilo Hive, ou seja /column_name=column_value/. Se um schema for fornecido, as colunas de partição descobertas usarão os tipos fornecidos no schema. Se as colunas de partição não fizerem parte do fornecido schema, as colunas de partição inferidas serão ignoradas.

Se existir uma coluna no esquema de partição e nas colunas de dados, o valor lido do valor de partição será usado em vez do valor de dados. Se você quiser ignorar os valores provenientes do diretório e usar a coluna de dados, poderá fornecer a lista de colunas de partição em uma lista separada por vírgulas com a opção partitionColumns.

A opção partitionColumns também pode ser usada para instruir read_files sobre quais colunas descobertas incluir no esquema inferido final. Fornecer uma cadeia de caracteres vazia ignora todas as colunas de partição.

A opção schemaHints também pode ser fornecida para substituir o esquema inferido para uma coluna de partição.

Os formatos TEXT e BINARYFILE têm um esquema fixo, mas read_files também tentam inferir o particionamento para esses formatos quando possível.

Autenticação para armazenamento em nuvem

read_files lê arquivos de locais externos do Catálogo do Unity ou volumes do Catálogo do Unity (gerenciados e externos). Você deve ter o READ FILES privilégio no local externo ou o READ VOLUME privilégio no volume que contém os arquivos que deseja ler. Consulte Conectar-se ao armazenamento de objetos de nuvem usando o Catálogo do Unity ou o que são volumes do Catálogo do Unity?.

Uso em tabelas de streaming

read_files pode ser usado em tabelas de streaming para ingerir arquivos no Delta Lake. read_files aproveita o Carregador Automático quando usado em uma consulta de tabela de streaming. Você deve usar o STREAM palavra-chave com read_files. Confira O que é Carregador Automático? para obter mais detalhes.

Quando usado em uma consulta de streaming, read_files usa um exemplo dos dados para inferir o esquema e pode evoluir o esquema à medida que processa mais dados. Confira Configurar a inferência e a evolução de esquema no Carregador Automático para obter mais detalhes.

Opções

• Opções básicas
• Opções específicas de formato
• Opções de streaming

Opções básicas

Opções específicas de formato

Para obter opções específicas para cada formato de arquivo (JSON, CSV, XML, Parquet, Avro, texto, ORC e binário), consulte as opções DataFrameReader.

Opções de streaming

Essas opções se aplicam ao usar read_files dentro de uma tabela de streaming ou consulta de streaming.

Exemplos

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);

Trabalhar com arquivos não estruturados

Os exemplos a seguir usam BINARYFILE o formato para ler e filtrar arquivos não estruturados armazenados em volumes do Catálogo do Unity e combinar read_files com funções de IA para processar o conteúdo do arquivo.

Liste todos os arquivos em um volume: use * EXCEPT (content) para retornar metadados de arquivo sem carregar conteúdo binário e selecione _metadata explicitamente para incluir campos de metadados no nível do arquivo.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>',
  format => 'binaryFile'
);

Listar arquivos de imagem filtrados por tamanho: use fileNamePattern para direcionar tipos de arquivo de imagem específicos e filtrar _metadata.file_size para retornar apenas arquivos dentro de um determinado intervalo de tamanho.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

Listar arquivos PDF modificados no último dia: use fileNamePattern para direcionar arquivos PDF e filtrar modificationTime para retornar apenas arquivos alterados no último dia.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,PDF}'
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

Executar uma função de IA em arquivos de imagem: use ai_query para processar arquivos de imagem lidos de um caminho de armazenamento em nuvem. Filtre em _metadata campos para direcionar arquivos específicos.

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Analisar documentos que correspondem a um padrão de nome de arquivo: use ai_parse_document para extrair conteúdo estruturado de PDFs e imagens. Filtre para _metadata.file_name direcionar arquivos específicos.

SELECT
  path AS file_path,
  ai_parse_document(
    content,
    map('version', '2.0')
  ) AS result
FROM read_files(
  '/Volumes/main/public/my_files/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';

Unir arquivos com uma tabela estruturada: fluxos de trabalho não estruturados geralmente exigem a mesclagem de dados estruturados armazenados em tabelas com arquivos não estruturados. O exemplo a seguir une arquivos em um caminho de armazenamento em nuvem com duas tabelas estruturadas, filtrando por tamanho de arquivo e um atributo de usuário. A junção é user_files feita extraindo a ID do arquivo do caminho do arquivo usando split e element_at.

SELECT
  users.user_id,
  user_files.file_id,
  files._metadata.file_name AS file_name,
  files.* EXCEPT (content),
  ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
  's3://my-bucket-name/files/',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
  ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
  ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
  AND files._metadata.file_size < 10000000;

Artigos relacionados

• CREATE STREAMING TABLE
• read_kafka Função com valor de tabela