read_files tabellvärdesfunktion

Gäller för: Databricks SQL Databricks Runtime 13.3 LTS och senare

Läser filer under en angivet plats och returnerar data i tabellformat.

Stöder läsning JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVROoch ORC filformat. Kan identifiera filformatet automatiskt och härleda ett enhetligt schema för alla filer.

Syntax

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

Argument

Den här funktionen kräver namngivna parameteranrop för alternativnycklarna.

• path: A STRING med URI för platsen för data. Stöder läsning från Azure Data Lake Storage Gen2 ('abfss://'), S3 (s3://) och Google Cloud Storage ('gs://'). Kan innehålla globs. Mer information finns i Filidentifiering .
• option_key: Namnet på alternativet som ska konfigureras. Du måste använda backticks (') för alternativ som innehåller punkter (.).
• option_value: Ett konstant uttryck som alternativet ska anges till. Accepterar literaler och skalärfunktioner.

Returer

En tabell som består av data från filer som lästs under den angivna path.

Filidentifiering

read_files kan läsa en enskild fil eller läsa filer under en angivet katalog. read_files identifierar alla filer under den angivna katalogen rekursivt om inte en glob tillhandahålls, vilket instruerar read_files att upprepas i ett specifikt katalogmönster.

Filtrera kataloger eller filer med hjälp av globmönster

Globmönster kan användas för att filtrera kataloger och filer när de anges i sökvägen.

read_files använder Auto Loader strikt globber när du identifierar filer med globs. Detta konfigureras med alternativet useStrictGlobber . När den strikta globbern är inaktiverad släpps avslutande snedstreck (/) och ett stjärnmönster som /*/ kan expandera till att upptäcka flera kataloger. Se exemplen nedan för att se skillnaden i beteende.

Schemahärledning

Schemat för filerna kan uttryckligen anges med read_files alternativet schema . När schemat inte har angetts read_files försöker du härleda ett enhetligt schema över de identifierade filerna, vilket kräver att alla filer läss om inte en LIMIT instruktion används. Även när du använder en LIMIT fråga kan en större uppsättning filer än vad som krävs läsas för att returnera ett mer representativt schema för data. Databricks lägger automatiskt till en LIMIT instruktion för SELECT frågor i notebook-filer och SQL-redigeraren om en användare inte har angett någon.

Alternativet schemaHints kan användas för att åtgärda delmängder av det härledda schemat. Mer information finns i Åsidosätta schemainferens med schematips.

A rescuedDataColumn tillhandahålls som standard för att rädda data som inte matchar schemat. Mer information finns i Vad är den räddade datakolumnen? Du kan släppa rescuedDataColumn alternativet genom att ange .schemaEvolutionMode => 'none'

Slutsatsdragning av partitionsschema

read_files kan också härleda partitioneringskolumner om filer lagras under Partitionerade kataloger i Hive-stil, dvs /column_name=column_value/. Om en schema anges använder de identifierade partitionskolumnerna de typer som anges i schema. Om partitionskolumnerna inte ingår i angivna schemaignoreras de härledda partitionskolumnerna.

Om det finns en kolumn i både partitionsschemat och i datakolumnerna används värdet som läse från partitionsvärdet i stället för datavärdet. Om du vill ignorera de värden som kommer från katalogen och använda datakolumnen kan du ange listan med partitionskolumner i en kommaavgränsad lista med alternativet partitionColumns .

Alternativet partitionColumns kan också användas för att instruera om read_files vilka identifierade kolumner som ska inkluderas i det slutliga härledda schemat. Om du anger en tom sträng ignoreras alla partitionskolumner.

Alternativet schemaHints kan också anges för att åsidosätta det härledda schemat för en partitionskolumn.

Formaten TEXT och BINARYFILE har ett fast schema, men read_files försöker också härleda partitionering för dessa format när det är möjligt.

Användning i strömningstabeller

read_files kan användas i strömmande tabeller för att mata in filer i Delta Lake. read_files utnyttjar automatisk inläsning när den används i en strömningstabellfråga. Du måste använda nyckelordet STREAM med read_files. Mer information finns i Vad är automatisk inläsning?

När det används i en direktuppspelningsfråga read_files använder du ett exempel på data för att härleda schemat och kan utveckla schemat när det bearbetar mer data. Mer information finns i Konfigurera schemainferens och utveckling i Auto Loader .

Alternativ

• Grundläggande alternativ
• Allmänna alternativ
• JSON Alternativ
• CSV Alternativ
• XML Alternativ
• PARQUET Alternativ
• AVRO Alternativ
• BINARYFILE Alternativ
• TEXT Alternativ
• ORC Alternativ
• Alternativ för direktuppspelning

Grundläggande alternativ

Allmänna alternativ

Följande alternativ gäller för alla filformat.

JSON Alternativ

CSV Alternativ

XML Alternativ

PARQUET Alternativ

AVRO Alternativ

BINARYFILE Alternativ

Binära filer har inga ytterligare konfigurationsalternativ.

TEXT Alternativ

ORC Alternativ

Alternativ för direktuppspelning

De här alternativen gäller när du använder read_files i en direktuppspelningstabell eller en direktuppspelningsfråga.

Exempel

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

Relaterade artiklar

• SKAPA DIREKTUPPSPELNINGSTABELL
• read_kafka tabellvärdesfunktion