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 Gen2 ('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 (') para opções que contêm ponto (.).
• option_value: uma expressão constante para a qual definir a opção. Aceita literais e funções escalares.

Retorna

Uma tabela composta pelos dados de arquivos lidos no determinado path.

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.

Filtrar 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. O Databricks adiciona automaticamente uma instrução LIMIT para SELECT consultas em notebooks e no editor de SQL se um usuário não tiver 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.

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 genéricas
• Opções JSON
• Opções CSV
• XML opções
• Opções PARQUET
• Opções AVRO
• Opções BINARYFILE
• Opções TEXT
• ORC opções
• Opções de streaming

Opções básicas

Opções genéricas

As opções a seguir se aplicam a todos os formatos de arquivo.

JSON options

CSV options

XML options

PARQUET options

AVRO options

BINARYFILE options

Os arquivos binários não têm nenhuma opção de configuração adicional.

TEXT options

ORC options

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

Artigos relacionados

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