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 ('abfss://'), S3 (s3://) och Google Cloud Storage ('gs://'). Kan innehålla globmönster. Se Filsökning för mer information.
• option_key: Namnet på alternativet som ska konfigureras. Du måste använda backticks () for options that contain dots (`).
• option_value: Ett konstant uttryck som alternativet ska anges till. Accepterar literaler och skalärfunktioner.

Returer

En tabell som innehåller data från filer som lästs under den angivna path. Schemat beror på filformatet:

• BINARYFILE: Returnerar ett fast schema:

  Kolumn	Type	beskrivning
  path	STRING	Hela sökvägen till filen.
  modificationTime	TIMESTAMP	Den senaste ändringstiden för filen.
  length	LONG	Storleken på filen i byte.
  content	BINARY	Filens binära innehåll. Använd * EXCEPT (content) för att exkludera binärt innehåll när du frågar efter filmetadata.

• TEXT: Returnerar ett fast schema med en enda value kolumn (STRING).

• Alla andra format (JSON, CSV, XML, PARQUET, AVRO, ORC): Schemat härleds från filinnehållet eller tillhandahålls uttryckligen schema med hjälp av alternativet.

_metadata Kolumn

read_files exponerar en _metadata kolumn med metadata på filnivå. Den här kolumnen ingår inte i SELECT * resultaten och måste uttryckligen väljas. Det innehåller följande fält:

Om du vill inkludera _metadata i resultat väljer du det explicit:

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

Filsökning

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 Loaders strikta globmönster när det upptäcker filer med globs. Detta konfigureras med alternativet useStrictGlobber . När den strikta globbern är inaktiverad tas avslutande snedstreck (/) bort, och ett stjärnmönster som /*/ kan utvidgas 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 till read_files med 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 ett LIMIT-uttalande för SELECT-frågor i notebooks och SQL-redigeraren om en användare inte har angett något.

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äses från partitionsschemat 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.

Autentisering för molnlagring

read_files läser filer från externa platser i Unity Catalog eller Unity Catalog-volymer (både hanterade och externa). Du måste ha behörigheten READ FILES på den externa platsen eller behörigheten READ VOLUME på volymen som innehåller de filer som du vill läsa. Se Ansluta till molnobjektlagring med Unity Catalog eller Vad är Unity Catalog-volymer?.

Användning i strömmande tabeller

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

När det används i en direktuppspelningsfråga, använder read_files ett urval av 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
• Formatspecifika alternativ
• Alternativ för direktuppspelning

Grundläggande alternativ

Formatspecifika alternativ

Alternativ som är specifika för varje filformat (JSON, CSV, XML, Parquet, Avro, text, ORC och binär fil) finns i DataFrameReader-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);

Arbeta med ostrukturerade filer

I följande exempel används BINARYFILE format för att läsa och filtrera ostrukturerade filer som lagras i Unity Catalog-volymer och kombinera read_files med AI-funktioner för att bearbeta filinnehåll.

Visa en lista över alla filer i en volym: Använd * EXCEPT (content) för att returnera filmetadata utan att läsa in binärt innehåll och välj _metadata uttryckligen att inkludera metadatafält på filnivå.

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

Lista bildfiler filtrerade efter storlek: Använd fileNamePattern för att rikta in specifika bildfiltyper och filtrera på _metadata.file_size för att endast returnera filer inom ett angivet storleksintervall.

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;

Lista PDF-filer som ändrats under den senaste dagen: Använd fileNamePattern för att rikta PDF-filer och filtrera på modificationTime för att endast returnera filer som ändrats under den senaste dagen.

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;

Kör en AI-funktion på bildfiler: Använd ai_query för att bearbeta bildfiler som lästs från en molnlagringssökväg. Filtrera på _metadata fält för att rikta in specifika filer.

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

Parsa dokument som matchar ett filnamnsmönster: Använd ai_parse_document för att extrahera strukturerat innehåll från PDF-filer och bilder. _metadata.file_name Filtrera efter för att rikta in specifika filer.

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

Koppla filer med en strukturerad tabell: Ostrukturerade arbetsflöden kräver ofta sammanslagning av strukturerade data som lagras i tabeller med ostrukturerade filer. I följande exempel kopplas filer till en molnlagringssökväg med två strukturerade tabeller, filtrering efter filstorlek och ett användarattribut. Kopplingen med user_files görs genom att extrahera fil-ID:t från filsökvägen med hjälp av split och 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;

Relaterade funktioner

• list_files tabellvärdesfunktion

Relaterade artiklar

• CREATE STREAMING TABLE
• read_kafka tabellvärdesfunktion