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.

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:

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.

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.

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

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.

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 Artikel

• CREATE STREAMING TABLE
• read_kafkaTabellenwertfunktion