read_files functie met tabelwaarde

Van toepassing op: Databricks SQL Databricks Runtime 13.3 LTS en hoger

Leest bestanden onder een opgegeven locatie en retourneert de gegevens in tabelvorm.

Ondersteunt het lezenJSON, CSV, XML, , TEXT, BINARYFILE, PARQUET, en AVROORCbestandsindelingen. Kan de bestandsindeling automatisch detecteren en een uniform schema afleiden voor alle bestanden.

Syntaxis

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

Argumenten

Voor deze functie is aanroepen van benoemde parameters vereist voor de optiesleutels.

• path: A STRING met de URI van de locatie van de gegevens. Ondersteunt het lezen van Azure Data Lake Storage ('abfss://'), S3 (s3://) en Google Cloud Storage ('gs://'). Kan globs bevatten. Zie Bestandsdetectie voor meer informatie.
• option_key: De naam van de optie die u wilt configureren. U moet backticks () for options that contain dots (.`) gebruiken.
• option_value: Een constante expressie om de optie in te stellen. Accepteert letterlijke en scalaire functies.

Retouren

Een tabel met de gegevens uit bestanden die onder de opgegeven pathbestanden worden gelezen. Het schema is afhankelijk van de bestandsindeling:

• BINARYFILE: retourneert een vast schema:

  Rubriek	Typ	Beschrijving
  path	STRING	Het volledige pad naar het bestand.
  modificationTime	TIMESTAMP	De laatste wijzigingstijd van het bestand.
  length	LONG	De grootte van het bestand in bytes.
  content	BINARY	De binaire inhoud van het bestand. Gebruik * EXCEPT (content) dit om binaire inhoud uit te sluiten bij het uitvoeren van query's op metagegevens van bestanden.

• TEXT: retourneert een vast schema met één value (STRING) kolom.

• Alle andere indelingen (JSON, CSV, XML, PARQUET, AVRO, ORC): het schema wordt afgeleid van de bestandsinhoud of expliciet opgegeven met behulp van de schema optie.

_metadata Kolom

read_files toont een _metadata kolom met metagegevens op bestandsniveau. Deze kolom is niet opgenomen in SELECT * de resultaten en moet expliciet worden geselecteerd. Deze bevat de volgende velden:

Als u de resultaten wilt opnemen _metadata , selecteert u deze expliciet:

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

Bestandsondekking

read_files kan een afzonderlijk bestand lezen of bestanden lezen onder een opgegeven map. read_files detecteert alle bestanden in de opgegeven map recursief, tenzij er een glob wordt opgegeven, die read_files instrueert om naar een specifiek mappatroon te recursieve.

Mappen of bestanden filteren met globpatronen

Glob-patronen kunnen worden gebruikt voor het filteren van mappen en bestanden wanneer deze in het pad worden opgegeven.

read_files maakt gebruik van de strikte globber van Auto Loader bij het detecteren van bestanden met globs. Dit wordt geconfigureerd door de useStrictGlobber optie. Wanneer de strikte globber is uitgeschakeld, worden afsluitende slashes (/) verwijderd en kan een sterpatroon zoals /*/ worden uitgebreid tot het vinden van meerdere mappen. Zie de onderstaande voorbeelden om het verschil in gedrag te zien.

Schema-afleiding

Het schema van de bestanden kan expliciet worden opgegeven read_files met de schema optie. Wanneer het schema niet wordt verstrekt, probeert read_files een uniform schema af te leiden voor de gedetecteerde bestanden, waarvoor alle bestanden moeten worden gelezen, tenzij een LIMIT instructie wordt gebruikt. Zelfs bij het gebruik van een LIMIT query kan een grotere set bestanden dan vereist is, worden gelezen om een representatiever schema van de gegevens te retourneren. Databricks voegt automatisch een LIMIT verklaring toe voor SELECT query's in notebooks en de SQL-editor als de gebruiker er nog geen heeft opgegeven.

De schemaHints optie kan worden gebruikt om subsets van het afgeleide schema aan te passen. Zie Schemadeductie overschrijven met schemahints voor meer informatie.

Er wordt standaard een rescuedDataColumn gegeven om gegevens te redden die niet overeenkomen met het schema. Zie Wat is de kolom met geredde gegevens? voor meer informatie. U kunt de rescuedDataColumn optie verwijderen door de optie schemaEvolutionMode => 'none'in te stellen.

Partitieschema-afleiding

read_fileskan ook partitioneringskolommen afleiden als bestanden worden opgeslagen onder gepartitioneerde directorieën in Hive-stijl, dat wil zeggen. Als er een schema is opgegeven, gebruiken de gedetecteerde partitiekolommen de typen in de schema. Als de partitiekolommen geen deel uitmaken van de opgegeven schema, worden de afgeleide partitiekolommen genegeerd.

Als er een kolom bestaat in zowel het partitieschema als in de gegevenskolommen, wordt de waarde die uit de partitiewaarde wordt gelezen, gebruikt in plaats van de gegevenswaarde. Als u de waarden uit de map wilt negeren en de gegevenskolom wilt gebruiken, kunt u de lijst met partitiekolommen opgeven in een door komma's gescheiden lijst met de partitionColumns optie.

De partitionColumns optie kan ook worden gebruikt om te instrueren read_files welke gedetecteerde kolommen moeten worden opgenomen in het uiteindelijke uitgestelde schema. Door het opgeven van een lege tekenreeks worden alle partitiekolommen genegeerd.

De schemaHints optie kan ook worden opgegeven om het uitgestelde schema voor een partitiekolom te overschrijven.

De TEXT indelingen en BINARYFILE indelingen hebben een vast schema, maar read_files proberen indien mogelijk ook partitionering voor deze indelingen af te leiden.

Verificatie voor cloudopslag

read_files leest bestanden van externe locaties van Unity Catalog of Unity Catalog-volumes (zowel beheerd als extern). U moet beschikken over de READ FILES bevoegdheid op de externe locatie of de READ VOLUME bevoegdheid op het volume dat de bestanden bevat die u wilt lezen. Zie Verbinding maken met cloudobjectopslag met behulp van Unity Catalog of Wat zijn Unity Catalog-volumes?

Gebruik in streaming-tabellen

read_files kan worden gebruikt in streamingtabellen om bestanden in te laden in Delta Lake. read_files maakt gebruik van Auto Loader wanneer het wordt gebruikt in een streamingtabelquery. U moet het STREAM trefwoord gebruiken met read_files. Zie Wat is automatisch laadprogramma? voor meer informatie.

Wanneer gebruikt in een streamingquery, read_files gebruikt een voorbeeld van de gegevens om het schema af te leiden en kan het schema evolueren naarmate er meer gegevens worden verwerkt. Zie Schemadeductie en evolutie configureren in AutoLoader voor meer informatie.

Opties

• Basisopties
• Opmaakspecifieke opties
• Streamingopties

Basismogelijkheden

Opmaakspecifieke opties

Zie de opties voor DataFrameReader voor opties die specifiek zijn voor elke bestandsindeling (JSON, CSV, XML, Parquet, Avro, tekst, ORC en binair).

Streamingopties

Deze opties zijn van toepassing wanneer u een read_files of streamingquery met gebruikt.

Voorbeelden

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

Werken met ongestructureerde bestanden

In de volgende voorbeelden wordt een indeling gebruikt BINARYFILE om ongestructureerde bestanden te lezen en te filteren die zijn opgeslagen in Unity Catalog-volumes en te combineren read_files met AI-functies om bestandsinhoud te verwerken.

Geef alle bestanden in een volume weer: Gebruik * EXCEPT (content) dit diagram om metagegevens van bestanden te retourneren zonder binaire inhoud te laden en selecteer _metadata expliciet metagegevensvelden op bestandsniveau op te nemen.

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

Lijst met afbeeldingsbestanden die zijn gefilterd op grootte: gebruik fileNamePattern deze indeling om specifieke bestandstypen voor afbeeldingen te targeten en te filteren _metadata.file_size om alleen bestanden binnen een bepaald groottebereik te retourneren.

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;

Pdf-bestanden weergeven die zijn gewijzigd binnen de afgelopen dag: Gebruik fileNamePattern dit om PDF-bestanden te targeten en te filteren modificationTime om alleen bestanden te retourneren die zijn gewijzigd binnen de afgelopen dag.

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;

Een AI-functie uitvoeren op afbeeldingsbestanden: gebruik ai_query deze functie om afbeeldingsbestanden te verwerken die worden gelezen vanuit een cloudopslagpad. Filter op _metadata velden om specifieke bestanden te targeten.

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

Documenten parseren die overeenkomen met een bestandsnaampatroon: gebruiken ai_parse_document om gestructureerde inhoud uit PDF's en afbeeldingen te extraheren. Filter op _metadata.file_name om specifieke bestanden te targeten.

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

Bestanden samenvoegen met een gestructureerde tabel: Ongestructureerde werkstromen vereisen vaak het samenvoegen van gestructureerde gegevens die zijn opgeslagen in tabellen met ongestructureerde bestanden. In het volgende voorbeeld worden bestanden samengevoegd in een cloudopslagpad met twee gestructureerde tabellen, filteren op bestandsgrootte en een gebruikerskenmerk. De join met user_files wordt uitgevoerd door de bestands-id uit het bestandspad te extraheren met behulp van split en 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;

Verwante artikelen:

• CREATE STREAMING TABLE
• read_kafka functie met tabelwaarde