read_files função com valor de tabela

Aplica-se a:selecionado Databricks SQL selecionado 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.

Observação

Disponível em Beta, configurado format => 'file' para devolver uma FILE referência para cada ficheiro em vez de ler o conteúdo do ficheiro. Veja FILE ficheiros de tipo e Ingestir como o tipo de ficheiro.

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:

Campo Tipo Descrição
file_path STRING O caminho completo para o arquivo de origem.
file_name STRING O nome do arquivo de origem.
file_size LONG O tamanho do arquivo de origem em bytes.
file_modification_time TIMESTAMP A última modificação do ficheiro fonte.
file_block_start LONG O início do bloco do ficheiro a ser lido.
file_block_length LONG O comprimento do bloco do ficheiro a ser lido.

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.

Padrão Descrição
? Corresponde a qualquer caractere
* Corresponde a zero ou mais caracteres
[abc] Corresponde a um único caractere do conjunto de caracteres {a,b,c}.
[a-z] Corresponde a um único caractere do intervalo de caracteres {a... z}.
[^a] Corresponde a um único caractere que não é do conjunto de caracteres ou intervalo {a}. Observe que o ^ caractere deve ocorrer imediatamente à direita do colchete de abertura.
{ab,cd} Corresponde a uma string do conjunto de strings {ab, cd}.
{ab,c{de, fh}} Corresponde a uma string do conjunto de strings {ab, cde, cfh}.

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.

Padrão Caminho do ficheiro Globber em modo estrito desativado Globber rigoroso ativado
/a/b /a/b/c/file.txt Sim Sim
/a/b /a/b_dir/c/file.txt Não Não
/a/b /a/b.txt Não Não
/a/b/ /a/b.txt Não Não
/a/*/c/ /a/b/c/file.txt Sim Sim
/a/*/c/ /a/b/c/d/file.txt Sim Sim
/a/*/d/ /a/b/c/d/file.txt Sim Não
/a/*/c/ /a/b/x/y/c/file.txt Sim Não
/a/*/c /a/b/c_file.txt Sim Não
/a/*/c/ /a/b/c_file.txt Sim Não
/a/*/c /a/b/cookie/file.txt Sim Não
/a/b* /a/b.txt Sim Sim
/a/b* /a/b/file.txt Sim Sim
/a/{0.txt,1.txt} /a/0.txt Sim Sim
/a/*/{0.txt,1.txt} /a/0.txt Não Não
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Sim Sim

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ção Tipo Descrição Valor predefinido
format String O formato de ficheiro de dados no caminho de origem. Auto-inferido se for omitido. Os valores permitidos incluem avro, binaryFile, csv, ( file Beta), json, orc, parquet, text, e xml. None
schema String O esquema dos ficheiros a ler. Especifique uma cadeia de esquema usando o formato DDL, por exemplo 'id int, ts timestamp, event string'. Se omitido, read_files tenta inferir um esquema unificado entre os ficheiros descobertos. None
inferColumnTypes Boolean Decidir se se deve inferir tipos exatos de coluna ao utilizar a inferência de esquema. Por padrão, as colunas são inferidas ao inferir conjuntos de dados JSON e CSV. Isto é o oposto do comportamento padrão do Auto Loader. Ver inferência de esquemas. true
partitionColumns String Uma lista separada por vírgulas de colunas de partição no estilo Hive para inferir a partir da estrutura de diretórios dos ficheiros. Colunas de partição em estilo colmeia são pares-chave-valor combinados por um sinal de igualdade, como <base-path>/a=x/b=1/c=y/file.format. Neste exemplo, as colunas de partição são a, be c. Se usar inferência de esquema e passar o <base-path> para carregar dados, estas colunas são automaticamente adicionadas ao seu esquema. Se especificar um esquema, o Auto Loader espera que estas colunas sejam incluídas no esquema. Se não quiseres que estas colunas façam parte do teu esquema, especifica "" ignorá-las. Também pode usar esta opção para inferir colunas a partir do caminho do ficheiro em estruturas de diretórios complexas. Por exemplo, para os ficheiros seguintes, especificando cloudFiles.partitionColumns como year,month,day retornos year=2022 para file1.csv, mas as month colunas e day são null. month e day são analisados corretamente para file2.csv e file3.csv:
<base-path>/year=2022/week=1/file1.csv
<base-path>/year=2022/month=2/day=3/file2.csv
<base-path>/year=2022/month=2/day=4/file3.csv		 None
schemaHints String Informação do esquema que passa ao Auto Loader durante a inferência do esquema. Veja dicas do esquema para mais detalhes. None
useStrictGlobber Boolean Se deve utilizar um globber estrito que corresponda ao comportamento padrão de globbing de outras fontes de arquivos no Apache Spark. Consulte Padrões comuns de carregamento de dados para obter mais detalhes. Disponível no Databricks Runtime 12.2 LTS e superior. Isto é o oposto do padrão do Auto Loader. true

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.

Opção Tipo Descrição Valor predefinido
allowOverwrites Boolean Se devo reprocessar ficheiros que mudam após a descoberta. Numa atualização, read_files reprocessa um ficheiro se este foi modificado após a última atualização bem-sucedida. false
includeExistingFiles Boolean Se deve incluir arquivos existentes no caminho de entrada de processamento de fluxo ou apenas processar novos arquivos que chegam após a configuração inicial. Essa opção é avaliada somente quando você inicia um fluxo pela primeira vez. Alterar essa opção depois de reiniciar o fluxo não tem efeito. true
maxBytesPerTrigger Byte String O número máximo de novos bytes a processar em cada trigger. Você pode especificar uma cadeia de caracteres de byte, como 10g para limitar cada microlote a 10 GB de dados. Este é um máximo suave. Se tiver ficheiros com 3 GB cada, o Azure Databricks processa 12 GB em microbatch. Quando usado em conjunto com maxFilesPerTrigger, Azure Databricks consome até ao limite inferior de maxFilesPerTrigger ou maxBytesPerTrigger, o que for atingido primeiro. Para tabelas de streaming criadas em armazéns SQL serverless, não defina esta opção ou maxFilesPerTrigger, para aproveitar o controlo dinâmico de admissão. None
maxFilesPerTrigger Integer O número máximo de ficheiros novos a processar em cada trigger. Quando usado em conjunto com maxBytesPerTrigger, Azure Databricks consome até ao limite inferior de maxFilesPerTrigger ou maxBytesPerTrigger, o que for atingido primeiro. Para tabelas de streaming criadas em armazéns SQL serverless, não defina esta opção ou maxBytesPerTrigger, para aproveitar o controlo dinâmico de admissão. 1000
schemaEvolutionMode String O modo para evoluir o esquema à medida que novas colunas são descobertas nos dados. Por padrão, as colunas são inferidas como cadeias de caracteres ao inferir conjuntos de dados JSON. Consulte a evolução do esquema para obter mais detalhes. Esta opção não se aplica a text e binaryFile ficheiros. "addNewColumns" Sem esquema, "none" caso contrário.
schemaLocation String O local para armazenar o esquema inferido e as alterações subsequentes. Consulte inferência de esquema para obter mais detalhes. A localização do esquema não é necessária quando usada numa consulta de tabela de streaming. None

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;
  • Last updated on