read_files função com valor de tabela

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

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 detetar o formato de arquivo automaticamente e inferir um esquema unificado em todos os arquivos.

Sintaxe

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

Argumentos

Esta função requer invocação de parâmetro nomeado para as chaves de opção.

• path: A STRING com o URI da localização dos dados. Suporta 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 os backticks () for options that contain dots (.`).
• option_value: Uma expressão constante para definir a opção. Aceita literais e funções escalares.

Devoluções

Uma tabela contendo os dados dos ficheiros lidos sob o dado path. O esquema depende do formato do ficheiro:

• BINARYFILE: Devolve um esquema fixo:

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

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

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

_metadata Coluna

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

Para incluir _metadata nos resultados, selecione explicitamente:

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

Descoberta de arquivos

read_files É capaz de ler um arquivo individual ou ler arquivos em um diretório fornecido. read_files descobre todos os ficheiros no diretório fornecido de forma recursiva, exceto se for fornecido um glob, que especifica ao read_files para recursar num padrão específico de diretório.

Filtrando diretórios ou arquivos usando padrões glob

Os padrões de Glob podem ser usados para filtrar diretórios e arquivos quando fornecidos no caminho.

read_files usa o globber rigoroso do Auto Loader ao identificar ficheiros com globs. Isso é configurado pela useStrictGlobber opção. Quando o globber estrito é desativado, as barras finais (/) são descartadas e um padrão de asterisco como /*/ pode expandir-se para descobrir vários diretórios. Veja os exemplos abaixo para ver a diferença de comportamento.

Inferência do esquema

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

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

A rescuedDataColumn é fornecido por padrão para recuperar quaisquer dados que não correspondam ao esquema. Consulte O que é a coluna de dados resgatados? para obter mais detalhes. Você pode soltar o rescuedDataColumn definindo a opção schemaEvolutionMode => 'none'.

Inferência de esquema de partição

read_files também pode inferir colunas de partição se os arquivos forem armazenados em diretórios particionados ao 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 a partir do valor da 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, você pode fornecer a lista de colunas de partição em uma lista separada por vírgulas com a partitionColumns opção.

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

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

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

Autenticação para armazenamento na nuvem

read_files lê ficheiros de localizações externas do Catálogo Unity ou volumes do Catálogo Unity (tanto geridos como externos). Deve ter o READ FILES privilégio na localização externa ou READ VOLUME o privilégio no volume que contém os ficheiros que quer ler. Veja Conectar-se ao armazenamento de objetos na nuvem usando o Unity Catalog ou O que são volumes do Unity Catalog?.

Uso em tabelas de streaming

read_files pode ser usado em tabelas de streaming para ingerir arquivos no Delta Lake. read_files tira partido do Auto Loader quando usado numa consulta de tabela de streaming. Você deve usar a STREAM palavra-chave com read_files. Consulte O que é o Auto Loader? para obter mais detalhes.

Quando usado em uma consulta de streaming, read_files usa uma amostra dos dados para inferir o esquema e pode evoluir o esquema à medida que processa mais dados. Consulte Configurar inferência e evolução de esquema no Auto Loader 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 opções específicas para cada formato de ficheiro (JSON, CSV, XML, Parquet, Avro, texto, ORC e binário), consulte opções DataFrameReader.

Opções de streaming

Essas opções se aplicam ao usar read_files numa tabela ou consulta de transmissão.

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

Trabalho com ficheiros não estruturados

Os exemplos seguintes usam BINARYFILE o formato para ler e filtrar ficheiros não estruturados armazenados em volumes do Catálogo Unity, e combinam-se read_files com funções de IA para processar o conteúdo dos ficheiros.

Liste todos os ficheiros num volume: Use * EXCEPT (content) para devolver metadados do ficheiro sem carregar conteúdo binário, e selecione _metadata explicitamente para incluir campos de metadados ao nível do ficheiro.

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

Listar ficheiros de imagem filtrados por tamanho: Use fileNamePattern para direcionar tipos específicos de ficheiros de imagem e filtre para _metadata.file_size devolver apenas ficheiros 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 ficheiros PDF modificados no último dia: Usar fileNamePattern para direcionar ficheiros PDF e filtrar modificationTime para devolver apenas ficheiros alterados no dia anterior.

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 ficheiros de imagem: Usar ai_query para processar ficheiros de imagem lidos a partir de um caminho de armazenamento na cloud. Filtra os _metadata campos para direcionar ficheiros 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 correspondam a um padrão de nomes de ficheiro: Usar ai_parse_document para extrair conteúdo estruturado de PDFs e imagens. Filtra por _metadata.file_name para direcionar ficheiros 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%';

Juntar ficheiros com uma tabela estruturada: Fluxos de trabalho não estruturados frequentemente exigem a fusão de dados estruturados armazenados em tabelas com ficheiros não estruturados. O exemplo seguinte une ficheiros num caminho de armazenamento na nuvem com duas tabelas estruturadas, filtrando pelo tamanho do ficheiro e por um atributo do utilizador. A junção com user_files é feita extraindo o ID do ficheiro do caminho do ficheiro 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