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 dei formati di file JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO e 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.

• path: un STRING con l'URI dell'ubicazione dei dati. Supporta la lettura da Azure Data Lake Storage ('abfss://'), S3 (s3://) e Google Cloud Storage ('gs://'). Può contenere glob. Vedi Scoperta dei file per ulteriori dettagli.
• option_key: nome dell'opzione da configurare. È necessario usare i backtick () for options that contain dots (.`).
• option_value: espressione costante su cui impostare l'opzione . Accetta valori letterali e funzioni scalari.

Restituiti

Tabella contenente i dati dei file letti nell'oggetto specificato path. Lo schema dipende dal formato di file:

• BINARYFILE: restituisce uno schema fisso:

  colonna	Tipo	Descrizione
  path	STRING	Percorso completo del file.
  modificationTime	TIMESTAMP	Ora dell'ultima modifica del file.
  length	LONG	Le dimensioni del file in byte.
  content	BINARY	Contenuto binario del file. Usare * EXCEPT (content) per escludere il contenuto binario durante l'esecuzione di query sui metadati del file.

• TEXT: restituisce uno schema fisso con una singola value colonna (STRING).

• Tutti gli altri formati (JSON, CSV, XML, PARQUET, AVRO, ORC): lo schema viene dedotto dal contenuto del file o fornito in modo esplicito usando l'opzione schema .

_metadata Colonna

read_files espone una _metadata colonna con metadati a livello di file. Questa colonna non è inclusa nei SELECT * risultati e deve essere selezionata in modo esplicito. Include i seguenti campi:

Per includere _metadata nei risultati, selezionarlo in modo esplicito:

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

Scoperta 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 di Auto Loader durante l'individuazione dei file tramite i globs. Questa opzione è configurata dall'opzione useStrictGlobber . Quando il globber rigido è disabilitato, le barre finali (/) vengono eliminate e un motivo a stella, /*/ ad esempio, può espandersi per individuare 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 alle query eseguite nei notebook e nell'editor SQL se l'utente non ne ha fornita una.

L'opzione schemaHints può essere usata per correggere i subset dello schema dedotto. Vedere Oltrepassare l'inferenza dello schema con suggerimenti di schema per ulteriori dettagli.

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

può anche dedurre le colonne di partizionamento se i file sono archiviati in directory partizionate in stile Hive , cioè . Se un schema viene specificato, le colonne di partizione individuate utilizzano 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.

È possibile specificare anche l'opzione schemaHints per sovrascrivere lo 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.

Autenticazione per l'archiviazione cloud

read_files legge i file dai percorsi esterni del catalogo Unity o dai volumi del catalogo Unity (gestiti ed esterni). È necessario avere il READ FILES privilegio per il percorso esterno o il READ VOLUME privilegio per il volume che contiene i file da leggere. Vedere Connettersi all'archiviazione di oggetti cloud usando il catalogo Unity o Che cosa sono i volumi del catalogo Unity?.

Utilizzo nelle tabelle di streaming

read_files può essere usato nelle tabelle di streaming per inserire file in Delta Lake. read_files utilizza Auto Loader in modo efficace quando viene impiegato in una query di una 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 specifiche del formato
• Opzioni di streaming

Opzioni standard

Opzioni specifiche del formato

Per le opzioni specifiche per ogni formato di file (JSON, CSV, XML, Parquet, Avro, text, ORC e binary), vedere Opzioni DataFrameReader.

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

Usare file non strutturati

Gli esempi seguenti usano il BINARYFILE formato per leggere e filtrare i file non strutturati archiviati nei volumi del catalogo Unity e combinarli read_files con le funzioni di intelligenza artificiale per elaborare il contenuto dei file.

Elencare tutti i file in un volume: usare * EXCEPT (content) per restituire i metadati dei file senza caricare il contenuto binario e selezionare _metadata in modo esplicito per includere campi di metadati a livello di file.

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

Elencare i file di immagine filtrati in base alle dimensioni: usare fileNamePattern per impostare come destinazione tipi di file di immagine specifici e filtrare in modo _metadata.file_size da restituire solo i file all'interno di un intervallo di dimensioni specificato.

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;

Elencare i file PDF modificati nell'ultimo giorno: usare fileNamePattern per impostare come destinazione i file PDF e filtrare in modo da modificationTime restituire solo i file modificati nell'ultimo giorno.

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;

Eseguire una funzione di intelligenza artificiale nei file di immagine: usare ai_query per elaborare i file di immagine letti da un percorso di archiviazione cloud. Filtrare in base ai _metadata campi per specificare i file di destinazione.

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%';

Analizzare i documenti corrispondenti a un modello di nome file: usare ai_parse_document per estrarre contenuto strutturato da PDF e immagini. Filtra in base _metadata.file_name a per specificare i file specifici.

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%';

Unire file con una tabella strutturata: i flussi di lavoro non strutturati spesso richiedono l'unione di dati strutturati archiviati in tabelle con file non strutturati. L'esempio seguente unisce i file in un percorso di archiviazione cloud con due tabelle strutturate, filtrando in base alle dimensioni del file e a un attributo utente. Il join con user_files viene eseguito estraendo l'ID file dal percorso del file 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;

Articoli correlati

• CREATE STREAMING TABLE
• read_kafka funzione con valori di tabella