read_files-Tabellenwertfunktion

Gilt für: Databricks SQL Databricks Runtime 13.3 LTS und höher

Liest Dateien an einem angegebenen Speicherort und gibt die Daten in Tabellenform zurück.

Unterstützt das Lesen der Dateiformate JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO und ORC. Kann das Dateiformat automatisch erkennen und ein einheitliches Schema für alle Dateien ableiten.

Hinweis

In der Beta verfügbar, so eingestellt format => 'file' , dass für jede Datei eine FILE Referenz zurückgegeben wird, anstatt den Inhalt der Datei zu lesen. SieheFILE Type und Ingest Dateien als DATEITYP.

Syntax

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

Argumente

Diese Funktion erfordert einen Aufruf benannter Parameter für die Optionsschlüssel.

• path: STRING mit dem URI des Speicherorts der Daten. Unterstützt das Lesen von Azure Data Lake Storage ('abfss://'), S3 (s3://) und Google Cloud Storage ('gs://'). Kann Globs enthalten. Ausführlichere Informationen finden Sie unter Dateiermittlung.
• option_key: Der Name der zu konfigurierenden Option. Sie müssen Backticks () for options that contain dots (.`) verwenden.
• option_value: Ein konstanter Ausdruck , auf den die Option festgelegt werden soll. Akzeptiert Literale und Skalarfunktionen.

Gibt zurück

Eine Tabelle, die die Daten aus Dateien enthält, die unter der angegebenen Datei gelesen werden path. Das Schema hängt vom Dateiformat ab:

• BINARYFILE: Gibt ein festes Schema zurück:

  Kolumne	Typ	BESCHREIBUNG
  path	STRING	Der vollständige Pfad zur Datei.
  modificationTime	TIMESTAMP	Der Zeitpunkt der letzten Änderung der Datei.
  length	LONG	Die Größe der Datei in Bytes.
  content	BINARY	Der binäre Inhalt der Datei. Wird verwendet * EXCEPT (content) , um binäre Inhalte beim Abfragen von Dateimetadaten auszuschließen.

• TEXT: Gibt ein festes Schema mit einer einzelnen value (STRING) Spalte zurück.

• Alle anderen Formate (JSON, CSV, XML, LAMINAT, AVRO, ORC): Das Schema wird aus dem Dateiinhalt abgeleitet oder explizit mithilfe der schema Option bereitgestellt.

_metadata Spalte

read_files macht eine _metadata Spalte mit Metadaten auf Dateiebene verfügbar. Diese Spalte ist nicht in SELECT * Den Ergebnissen enthalten und muss explizit ausgewählt werden. Er enthält die folgenden Felder:

Feld	Typ	BESCHREIBUNG
file_path	STRING	Der vollständige Pfad zur Quelldatei.
file_name	STRING	Der Name der Quelldatei.
file_size	LONG	Die Größe der Quelldatei in Byte.
file_modification_time	TIMESTAMP	Der Zeitpunkt der letzten Änderung der Quelldatei.
file_block_start	LONG	Der Anfang des zu lesenden Dateiblocks.
file_block_length	LONG	Die Länge des Zu lesenden Dateiblocks.

Um ergebnisse einzuschließen _metadata , wählen Sie sie explizit aus:

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

Dateiermittlung

read_files kann eine einzelne Datei oder Dateien in einem bereitgestellten Verzeichnis lesen. read_files ermittelt alle Dateien im bereitgestellten Verzeichnis rekursiv, es sei denn, es wird ein Glob angegeben. Dadurch wird read_files angewiesen, ein bestimmtes Verzeichnismuster rekursiv zu durchlaufen.

Filtern von Verzeichnissen oder Dateien mithilfe von Globmustern

Globmuster können zum Filtern von Verzeichnissen und Dateien verwendet werden, wenn sie im Pfad angegeben werden.

Muster	BESCHREIBUNG
?	Führt einen Abgleich für ein einzelnes Zeichen durch
*	Entspricht null oder mehr Zeichen
[abc]	Entspricht einem einzelnen Zeichen aus dem Zeichensatz {a,b,c}.
[a-z]	Entspricht einem einzelnen Zeichen aus dem Zeichenbereich {a... z}.
[^a]	Entspricht einem einzelnen Zeichen, das nicht aus dem Zeichensatz oder Bereich {a} stammt. Beachten Sie, dass das Zeichen ^ sofort rechts neben der öffnenden Klammer auftreten muss.
{ab,cd}	Entspricht einer Zeichenfolge aus dem Zeichenfolgensatz {ab, cd}.
{ab,c{de, fh}}	Entspricht einer Zeichenfolge aus dem Zeichenfolgensatz {ab, cde, cfh}.

read_files verwendet die strenge Globber des Auto Loaders beim Ermitteln von Dateien mit Globs. Dies wird durch die Option useStrictGlobber konfiguriert. Wenn der strenge Globber deaktiviert ist, werden nachgestellte Schrägstriche (/) gelöscht, und ein Sternmuster (etwa /*/) kann zur Ermittlung mehrerer Verzeichnisse erweitert werden. In den folgenden Beispiele ist der Unterschied im Verhalten zu sehen.

Muster	Dateipfad	Strenger Globber deaktiviert	Strenger Globber aktiviert
/a/b	/a/b/c/file.txt	Ja	Ja
/a/b	/a/b_dir/c/file.txt	Nein	Nein
/a/b	/a/b.txt	Nein	Nein
/a/b/	/a/b.txt	Nein	Nein
/a/*/c/	/a/b/c/file.txt	Ja	Ja
/a/*/c/	/a/b/c/d/file.txt	Ja	Ja
/a/*/d/	/a/b/c/d/file.txt	Ja	Nein
/a/*/c/	/a/b/x/y/c/file.txt	Ja	Nein
/a/*/c	/a/b/c_file.txt	Ja	Nein
/a/*/c/	/a/b/c_file.txt	Ja	Nein
/a/*/c	/a/b/cookie/file.txt	Ja	Nein
/a/b*	/a/b.txt	Ja	Ja
/a/b*	/a/b/file.txt	Ja	Ja
/a/{0.txt,1.txt}	/a/0.txt	Ja	Ja
/a/*/{0.txt,1.txt}	/a/0.txt	Nein	Nein
/a/b/[cde-h]/i/	/a/b/c/i/file.txt	Ja	Ja

Schemarückschluss

Das Schema der Dateien kann mit der Option read_files explizit für schema angegeben werden. Wenn das Schema nicht bereitgestellt wird, versucht read_files, ein einheitliches Schema für die ermittelten Dateien abzuleiten. Das macht das Lesen aller Dateien erforderlich, es sei denn, es wird eine LIMIT-Anweisung verwendet. Auch bei Verwendung einer LIMIT-Abfrage werden möglicherweise mehr Dateien gelesen als erforderlich, um ein repräsentativeres Schema der Daten zurückzugeben. Databricks fügt automatisch eine LIMIT Anweisung für SELECT Abfragen in Notizbüchern und dem SQL-Editor hinzu, wenn ein Benutzer keines angegeben hat.

Die Option schemaHints kann verwendet werden, um Teilmengen des abgeleiteten Schemas zu korrigieren. Ausführlichere Informationen finden Sie unter Außerkraftsetzung des Schemarückschlusses mit Schemahinweisen.

Eine rescuedDataColumn wird standardmäßig bereitgestellt, um alle Daten zu retten, die nicht mit dem Schema übereinstimmen. Ausführlichere Informationen finden Sie unter Was ist die Spalte „rescued data“ (gerettete Daten)?. Sie können rescuedDataColumn löschen, indem Sie die Option schemaEvolutionMode => 'none' festlegen.

Partitionsschemarückschluss

read_files kann auch Partitionierungsspalten ableiten, wenn Dateien in im Hive-Stil partitionierten Verzeichnissen gespeichert werden, d. h. /column_name=column_value/. Wenn ein schema angegeben wird, nutzen die ermittelten Partitionsspalten die in schema bereitgestellten Typen. Wenn die Partitionsspalten nicht Teil des bereitgestellten Schemas (schema) sind, werden die abgeleiteten Partitionsspalten ignoriert.

Wenn eine Spalte sowohl im Partitionsschema als auch in den Datenspalten vorhanden ist, wird anstelle des Datenwerts der Wert verwendet, der aus dem Partitionswert gelesen wird. Wenn Sie die Werte aus dem Verzeichnis ignorieren und die Datenspalte verwenden möchten, können Sie die Liste der Partitionsspalten in einer durch Trennzeichen getrennten Liste mit der Option partitionColumns angeben.

Die Option partitionColumns kann auch verwendet werden, um read_files anzuweisen, welche ermittelten Spalten in das endgültige abgeleitete Schema eingeschlossen werden sollen. Wenn Sie eine leere Zeichenfolge angeben, werden alle Partitionsspalten ignoriert.

Die Option schemaHints kann auch bereitgestellt werden, um das abgeleitete Schema für eine Partitionsspalte zu überschreiben.

Die Formate TEXT und BINARYFILE weisen ein festes Schema auf, read_files versucht aber ebenfalls, nach Möglichkeit eine Partitionierung für diese Formate abzuleiten.

Authentifizierung für Cloudspeicher

read_files liest Dateien von externen Speicherorten des Unity-Katalogs oder Unity-Katalogvolumes (sowohl verwaltet als auch extern). Sie müssen über die READ FILES Berechtigungen für den externen Speicherort oder das READ VOLUME Recht auf dem Volume verfügen, das die Dateien enthält, die Sie lesen möchten. Siehe Verbinden mit Cloudobjektspeicher mit Unity-Katalog oder Was sind Unity-Katalogvolumes?.

Verwendung in Streamingtabellen

read_files kann in Streamingtabellen verwendet werden, um Dateien in Delta Lake zu erfassen. Bei Verwendung in einer Streamingtabellenabfrage nutzt read_files den Autoloader. Sie müssen das Schlüsselwort STREAM mit read_files verwenden. Ausführlichere Informationen finden Sie unter Automatisches Laden.

Bei Verwendung in einer Streamingabfrage verwendet read_files eine Stichprobe der Daten zum Ableiten des Schemas. Das Schema kann bei der Verarbeitung weiterer Daten spontan weiterentwickelt werden. Weitere Informationen finden Sie unter Schemarückschluss und -entwicklung in Auto Loader konfigurieren.

Tastatur

• Grundlegende Optionen
• Formatspezifische Optionen
• Streamingoptionen

Grundlegende Optionen

Auswahlmöglichkeit	Typ	BESCHREIBUNG	Standardwert
format	String	Das Datendateiformat im Quellpfad. Automatisch abgeleitet, wenn es ausgelassen wird. Erlaubte Werte umfassen , , , (Beta), json, orc, , textparquet, , und xml. filecsvbinaryFileavro	Nichts
schema	String	Das Schema der zu lesenden Dateien. Spezifiziere zum Beispiel 'id int, ts timestamp, event string'eine Schema-Zeichenkette im DDL-Format. Wenn ausgelassen, versucht es, read_filesein einheitliches Schema über die entdeckten Dateien zu leiten.	Nichts
inferColumnTypes	Boolean	Gibt an, ob exakte Spaltentypen abgeleitet werden sollen, wenn der Schemarückschluss verwendet wird. Standardmäßig werden Spalten abgeleitet, wenn JSON- und CSV-Datasets abgeleitet werden. Das ist das Gegenteil des Standardverhaltens von Auto Loader. Siehe Schema-Inferenz.	true
partitionColumns	String	Eine komma-getrennte Liste von Hive-ähnlichen Partitionsspalten, um aus der Verzeichnisstruktur der Dateien abzuleiten. Hive-Style-Partitionsspalten sind Schlüssel-Wert-Paare, die durch ein Gleichheitszeichen kombiniert werden, wie zum Beispiel <base-path>/a=x/b=1/c=y/file.format. In diesem Beispiel sind die Partitionsspalten a, bund c. Wenn du die Schema-Inferenz verwendest und die Daten <base-path> zum Laden übergibst, werden diese Spalten automatisch zu deinem Schema hinzugefügt. Wenn Sie ein Schema angeben, erwartet auto Loader, dass diese Spalten im Schema enthalten sind. Wenn du diese Spalten nicht Teil deines Schemas haben möchtest, gib an "" , sie zu ignorieren. Sie können diese Option auch nutzen, um Spalten aus dem Dateipfad in komplexen Verzeichnisstrukturen abzuleiten. Zum Beispiel für die folgenden Dateien, wobei cloudFiles.partitionColumns als year,month,day Rückgabe für file1.csvgegeben year=2022 wird, aber die month Spalten day und die Spalten sind null. month und day werden korrekt für file2.csv und file3.csvgeparst: <base-path>/year=2022/week=1/file1.csv <base-path>/year=2022/month=2/day=3/file2.csv <base-path>/year=2022/month=2/day=4/file3.csv	Nichts
schemaHints	String	Schema-Informationen, die du während der Schema-Inferenz an den Auto Loader weitergibst. Weitere Informationen finden Sie unter Schemahinweise.	Nichts
useStrictGlobber	Boolean	Gibt an, ob ein strenger Globber verwendet werden soll, der dem Standard-Globbingverhalten anderer Dateiquellen in Apache Spark entspricht. Ausführlichere Informationen finden Sie unter Allgemeine Muster zum Laden von Daten. Verfügbar in Databricks Runtime 12.2 LTS und höher. Das ist das genaue Gegenteil von der Standardeinstellung für Auto Loader.	true

Formatspezifische Optionen

Optionen speziell für jedes Dateiformat (JSON, CSV, XML, Parkett, Avro, Text, ORC und Binärdatei) finden Sie unter DataFrameReader-Optionen.

Streamingoptionen

Diese Optionen gelten bei Verwendung von read_files innerhalb einer Streamingtabelle oder Streamingabfrage.

Auswahlmöglichkeit	Typ	BESCHREIBUNG	Standardwert
allowOverwrites	Boolean	Ob Dateien, die sich nach der Entdeckung ändern, neu verarbeitet werden sollen. Bei einer Aktualisierung wird eine Datei neu verarbeitet, read_files wenn sie nach der letzten erfolgreichen Aktualisierung geändert wurde.	false
includeExistingFiles	Boolean	Gibt an, ob vorhandene Dateien in den Eingabepfad für die Streamverarbeitung einbezogen werden, oder ob nur neue Dateien verarbeitet werden sollen, die nach der Ersteinrichtung eingehen. Diese Option wird nur ausgewertet, wenn Sie einen Stream zum ersten Mal starten. Das Ändern dieser Option nach dem Neustart des Streams hat keine Auswirkungen.	true
maxBytesPerTrigger	Byte String	Die maximale Anzahl neuer Bytes, die in jedem Trigger verarbeitet werden müssen. Sie können eine Bytezeichenfolge wie z. B. 10g angeben, um jeden Microbatch auf 10 GB Daten zu beschränken. Dies ist ein weicher Maximalwert. Wenn Sie über Dateien mit jeweils 3 GB verfügen, verarbeitet Azure Databricks 12 GB in einem Mikrobatch. Bei Verwendung mit maxFilesPerTrigger verbraucht Azure Databricks bis zur unteren Grenze von maxFilesPerTrigger oder maxBytesPerTrigger, je nachdem, welches zuerst erreicht wird. Für Streaming-Tabellen, die auf serverlosen SQL-Warehouses erstellt wurden, setze diese Option nicht oder maxFilesPerTrigger, um dynamische Zutrittskontrolle zu nutzen.	Nichts
maxFilesPerTrigger	Integer	Die maximale Anzahl neuer Dateien, die in jedem Trigger verarbeitet werden müssen. Bei Verwendung mit maxBytesPerTrigger verbraucht Azure Databricks bis zur unteren Grenze von maxFilesPerTrigger oder maxBytesPerTrigger, je nachdem, welches zuerst erreicht wird. Für Streaming-Tabellen, die auf serverlosen SQL-Warehouses erstellt wurden, setze diese Option nicht oder maxBytesPerTrigger, um dynamische Zutrittskontrolle zu nutzen.	1000
schemaEvolutionMode	String	Der Modus zum Weiterentwickeln des Schemas, wenn neue Spalten in den Daten ermittelt werden. Standardmäßig werden Spalten als Zeichenfolgen abgeleitet, wenn JSON-Datasets abgeleitet werden. Weitere Informationen finden Sie unter Schemaentwicklung. Diese Option gilt nicht für text und binaryFile Dateien.	"addNewColumns" ohne Schema, "none" ansonsten.
schemaLocation	String	Der Speicherort, an dem das abgeleitete Schema und nachfolgende Änderungen gespeichert werden. Weitere Informationen finden Sie unter Schemarückschluss. Der Schema-Standort ist bei Verwendung in einer Streaming-Tabellen-Abfrage nicht erforderlich.	Nichts

Beispiele

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

Arbeiten mit unstrukturierten Dateien

In den folgenden Beispielen wird BINARYFILE das Format zum Lesen und Filtern unstrukturierter Dateien verwendet, die in Unity-Katalogvolumes gespeichert sind, und mit KI-Funktionen zum Verarbeiten von Dateiinhalten kombiniert read_files .

Auflisten aller Dateien in einem Volume: Dient * EXCEPT (content) zum Zurückgeben von Dateimetadaten, ohne binäre Inhalte zu laden, und wählen Sie _metadata explizit aus, um Metadatenfelder auf Dateiebene einzuschließen.

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

Nach Größe gefilterte Bilddateien auflisten: Wird fileNamePattern verwendet, um bestimmte Bilddateitypen zu adressieren und zu filtern _metadata.file_size , um nur Dateien innerhalb eines bestimmten Größenbereichs zurückzugeben.

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-Dateien auflisten, die innerhalb des letzten Tages geändert wurden: Wird fileNamePattern verwendet, um PDF-Dateien als Ziel zu verwenden und zu filtern modificationTime , um nur dateien zurückzugeben, die innerhalb des letzten Tages geändert wurden.

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;

Ausführen einer KI-Funktion für Bilddateien: Wird ai_query zum Verarbeiten von Bilddateien verwendet, die aus einem Cloudspeicherpfad gelesen werden. Filtern Sie nach _metadata Feldern, um bestimmte Dateien zu adressieren.

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

Analysieren Sie Dokumente, die mit einem Dateinamenmuster übereinstimmen: Verwenden Sie ai_parse_document diese Methode, um strukturierte Inhalte aus PDF-Dateien und Bildern zu extrahieren. Filtern Sie nach _metadata.file_name bestimmten Dateien.

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

Verknüpfen von Dateien mit einer strukturierten Tabelle: Unstrukturierte Workflows erfordern häufig das Zusammenführen strukturierter Daten, die in Tabellen mit unstrukturierten Dateien gespeichert sind. Im folgenden Beispiel werden Dateien in einem Cloudspeicherpfad mit zwei strukturierten Tabellen verknüpft, die nach Dateigröße und benutzeratribut gefiltert werden. Die Verknüpfung erfolgt durch user_files Extrahieren der Datei-ID aus dem Dateipfad mithilfe split und 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;

Verwandte Funktionen

• list_filesTabellenwertfunktion

Verwandte Artikel

• CREATE STREAMING TABLE
• read_kafkaTabellenwertfunktion