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 do 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 composta pelos dados dos ficheiros lidos conforme o dado path.

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.

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

CSV Opções

XML Opções

PARQUET Opções

AVRO Opções

BINARYFILE Opções

Os ficheiros binários não têm quaisquer opções de configuração adicionais.

TEXT Opções

ORC Opções

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

Artigos relacionados

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