read_files funzione con valori di tabella

Si applica a: Databricks SQL Databricks Runtime 13.3 LTS e versioni successive

Legge i file in un percorso specificato e restituisce i dati in formato tabulare.

Supporta la lettura JSONdei XMLTEXTPARQUETBINARYFILEAVROformati di file , CSVe .ORC Può rilevare automaticamente il formato di file e dedurre uno schema unificato in tutti i file.

Sintassi

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

Argomenti

Questa funzione richiede la chiamata di parametri denominati per le chiavi di opzione.

• pathSTRING: oggetto con l'URI della posizione dei dati. Supporta la lettura da Azure Data Lake Storage Gen2 ('abfss://'), S3 (s3://) e Google Cloud Storage ('gs://'). Può contenere glob. Per altri dettagli, vedere Individuazione file.
• option_key: nome dell'opzione da configurare. È necessario usare i backtick (') per le opzioni che contengono punti (.).
• option_value: espressione costante su cui impostare l'opzione . Accetta valori letterali e funzioni scalari.

Valori restituiti

Tabella costituita dai dati dei file letti nell'oggetto specificato path.

Individuazione file

read_files può leggere un singolo file o leggere i file in una directory specificata. read_files individua tutti i file nella directory specificata in modo ricorsivo, a meno che non venga fornito un GLOB , che indica read_files di ripetere il processo in un modello di directory specifico.

Filtro di directory o file usando modelli GLOB

I modelli Glob possono essere usati per filtrare directory e file quando specificati nel percorso.

read_files usa il globber rigido del caricatore automatico durante l'individuazione dei file con glob. Questa opzione è configurata dall'opzione useStrictGlobber . Quando il globber rigido è disabilitato, le barre finali (/) vengono eliminate e un modello a stella, /*/ ad esempio, può espandersi nell'individuazione di più directory. Vedere gli esempi seguenti per vedere la differenza nel comportamento.

Inferenza dello schema

Lo schema dei file può essere fornito in modo esplicito a read_files con l'opzione schema . Quando lo schema non viene specificato, read_files tenta di dedurre uno schema unificato tra i file individuati, che richiede la lettura di tutti i file, a meno che non venga usata un'istruzione LIMIT . Anche quando si usa una LIMIT query, potrebbe essere letto un set di file di dimensioni maggiori di quello necessario per restituire uno schema più rappresentativo dei dati. Databricks aggiunge automaticamente un'istruzione LIMIT per SELECT le query nei notebook e l'editor SQL se non ne è stato specificato uno.

L'opzione schemaHints può essere usata per correggere i subset dello schema dedotto. Per altri dettagli, vedere Eseguire l'override dell'inferenza dello schema con hint dello schema.

Un rescuedDataColumn oggetto viene fornito per impostazione predefinita per salvare tutti i dati che non corrispondono allo schema. Per altri dettagli, vedere Che cos'è la colonna di dati salvata? È possibile eliminare rescuedDataColumn impostando l'opzione schemaEvolutionMode => 'none'.

Inferenza dello schema di partizione

read_filespuò anche dedurre le colonne di partizionamento se i file vengono archiviati in directory partizionate in stile Hive, ovvero /column_name=column_value/. Se viene specificato , schema le colonne di partizione individuate usano i tipi forniti in schema. Se le colonne di partizione non fanno parte dell'oggetto specificato schema, le colonne di partizione dedotte vengono ignorate.

Se esiste una colonna sia nello schema di partizione che nelle colonne di dati, viene usato il valore letto dal valore della partizione anziché il valore di dati. Se si desidera ignorare i valori provenienti dalla directory e usare la colonna di dati, è possibile fornire l'elenco di colonne di partizione in un elenco delimitato da virgole con l'opzione partitionColumns .

L'opzione partitionColumns può essere usata anche per indicare read_files sulle colonne individuate da includere nello schema dedotto finale. Se si specifica una stringa vuota, tutte le colonne di partizione vengono ignorate.

È schemaHints anche possibile specificare l'opzione per eseguire l'override dello schema dedotto per una colonna di partizione.

I TEXT formati e BINARYFILE hanno uno schema fisso, ma read_files tenta anche di dedurre il partizionamento per questi formati, quando possibile.

Utilizzo nelle tabelle di streaming

read_files può essere usato nelle tabelle di streaming per inserire file in Delta Lake. read_files sfrutta il caricatore automatico quando viene usato in una query di tabella di streaming. È necessario usare la STREAM parola chiave con read_files. Per altri dettagli, vedere Che cos'è il caricatore automatico?

Se usato in una query di streaming, read_files usa un esempio di dati per dedurre lo schema e può evolvere lo schema man mano che elabora più dati. Per altri dettagli, vedere Configurare l'inferenza e l'evoluzione dello schema in Caricamento automatico.

Opzioni

• Opzioni di base
• Opzioni generiche
• JSONopzioni
• CSVopzioni
• XMLopzioni
• PARQUETopzioni
• AVROopzioni
• BINARYFILEopzioni
• TEXTopzioni
• ORC Opzioni
• Opzioni di streaming

Opzioni standard

Opzioni generiche

Le opzioni seguenti si applicano a tutti i formati di file.

Opzioni JSON

Opzioni CSV

Opzioni XML

Opzioni PARQUET

Opzioni AVRO

Opzioni BINARYFILE

I file binari non dispongono di opzioni di configurazione aggiuntive.

Opzioni TEXT

Opzioni ORC

Opzioni di streaming

Queste opzioni si applicano quando si usa read_files all'interno di una tabella di streaming o di una query di streaming.

Esempi

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

Articoli correlati

• CREATE STREAMING TABLE
• Funzione con valori di tabella read_kafka