Dateien als FILE-Typ eintragen

Important

Dieses Feature befindet sich in der Betaversion.

Der FILE Typ speichert und fragt Verweise auf unstrukturierte Dateien (Dokumente, Bilder und Audio) in Tabellen ab. Diese Seite zeigt, wie man Dateien entdeckt, als FILE Referenzen einnimmt und neue Dateien schrittweise einführt, sobald sie eintreffen.

Für die Referenz zum Typ FILE siehe FILE Typ. Für einen Überblick über Ansätze zur Erfassung unstrukturierter Daten siehe FILE type and unstructured data.

Hinweis

FILE Spalten haben keine definierte Reihenfolge. Du kannst eine FILE Spalte nicht als Partitionierungsspalte, Clustering-Spalte oder Z-Ordnungsschlüssel verwenden. Weitere Informationen finden Sie unter Grenzwerte.

Speichermodi

Eine Referenz FILE kann in einem von zwei Modi gespeichert werden:

FILE MANAGEDEs speichert Kopien von Dateien im von Unity Catalog verwalteten Speicher: Berechtigungen werden über die Tabelle verwaltet, und das Löschen von Zeilen gibt die referenzierten Dateien für die Garbage Collection frei, sodass die Tabelle und ihre Dateien synchron bleiben. Dateien aus Quellen außerhalb von Volumes, wie SharePoint, Google Drive oder SFTP, müssen als FILE MANAGED importiert und gespeichert werden.
FILE EXTERNAL verweist auf Dateien, die bereits in einem Unity-Katalog-Volume existieren. Databricks unterstützt nicht das Speichern von FILE EXTERNAL Referenzen für Dateien, die außerhalb von Volumes gespeichert sind.

Azure Databricks empfiehlt FILE MANAGED für Workloads, die von Dateiberechtigungen und integrierter Compliance profitieren. Für einen Vergleich von Governance und Lebenszyklusverhalten siehe FILE-Typ und unstrukturierte Daten.

Verwenden Sie `list_files`, um Dateien zu finden

Verwenden Sie die list_files tabellenwertige Funktion, um die unter einem Pfad verfügbaren Dateien zu ermitteln. Sie gibt pro Datei eine Zeile mit path, size, modification_time und einer FILE-Referenz zurück:

SELECT * FROM list_files('/Volumes/my_catalog/my_schema/raw_files/');

Um Dateien in einer Quellquelle, die eine Unity-Catalog-Verbindung benötigt, wie SharePoint, Google Drive oder SFTP, zu entdecken, fügen Sie den Parameter hinzuconnection:

SELECT * FROM list_files('https://example.sharepoint.com/sites/my-site/', connection => 'my_sharepoint_connection');

list_files Entdeckt Dateien standardmäßig rekursiv. Um mehr zu erfahren, siehe list_files tabellenwertige Funktion.

Dateien als FILE-Referenzen eintragen

Wählen Sie je nachdem, wo Sie Ihre Dateien speichern, eine Erfassungsmethode aus. Um Dateien von einer externen Quelle zu übertragen, kopieren Sie sie in verwalteten Speicher als FILE MANAGED. Um auf Dateien zu verweisen, die sich bereits in einem Unity-Catalog-Volume befinden, ohne sie zu kopieren, verwenden Sie FILE EXTERNAL.

Externe Quellcodedateien als FILE MANAGED eintragen

Um FILEReferenzen für Dateien in einer Quelle wie SharePoint, Google Drive oder SFTP zu generieren, importieren Sie die Dateien zuerst und speichern Sie sie als FILE MANAGED. FILE EXTERNAL wird für Dateien, die außerhalb der Volumes gespeichert sind, nicht unterstützt.

Das folgende Beispiel überträgt Dateien von SharePoint in eine FILE MANAGED Tabelle:

SQL

CREATE TABLE managed_documents (
  file_name STRING,
  path STRING,
  size BIGINT,
  modification_time TIMESTAMP,
  file FILE MANAGED
) USING DELTA
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/');

INSERT INTO managed_documents
  SELECT _metadata.file_name, *
  FROM read_files(
    'https://example.sharepoint.com/sites/my-site/',
    connection => 'my_sharepoint_connection',
    format => 'file');

Python

(spark.read.format("file")
  .option("databricks.connection", "my_sharepoint_connection")
  .load("https://example.sharepoint.com/sites/my-site/")
  .selectExpr("_metadata.file_name", "*")
  .writeTo("managed_documents").append())

Scala

spark.read.format("file")
  .option("databricks.connection", "my_sharepoint_connection")
  .load("https://example.sharepoint.com/sites/my-site/")
  .selectExpr("_metadata.file_name", "*")
  .writeTo("managed_documents").append()

Volume-Dateien als FILE EXTERNAL einlesen

Um bereits in einem Unity-Katalog-Volume vorhandene Dateien einzulesen, verwenden Sie eine CREATE TABLE AS SELECT (CTAS)-Anweisung mit list_files. Dies erstellt eine Tabelle mit einer Spalte FILE EXTERNAL , die jede Datei an Ort und Stelle referenziert, ohne deren Inhalt zu kopieren. Das folgende Beispiel erstellt eine Tabelle documents mit Dateinamen, Metadaten und einer FILE Referenz für jede Datei:

CREATE TABLE documents AS
  SELECT _metadata.file_name, *
  FROM list_files('/Volumes/my_catalog/my_schema/raw_files/');

Verwenden Sie Pipelines, um neue Dateien inkrementell aufzunehmen

Um neue Dateien beim Eintreffen einzulesen, verwenden Sie eine Streaming-Tabelle in einer Lakeflow-Pipeline, die die Quelle mit STREAM read_files(..., format => 'file') liest. Jedes Pipeline-Update verarbeitet nur die nach dem letzten Update hinzugefügten Dateien. Siehe read_files und Spark Declarative Pipelines.

Um Dateien schrittweise von einer Quelle wie Google Drive zu streamen:

Setze den Kanal der Pipeline auf PREVIEW. Das Einlesen von FILE-Referenzen in einer Pipeline erfordert den Kanal PREVIEW.

Definiere eine Streaming-Tabelle, die die Quelle mit STREAM read_files(..., format => 'file')liest, wie im folgenden Code:

SQL

CREATE STREAMING TABLE streaming_documents (
  path STRING,
  size BIGINT,
  modification_time TIMESTAMP,
  file FILE MANAGED
)
TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/')
AS SELECT *
  FROM STREAM read_files(
    'https://drive.google.com/drive/folders/my-folder-id',
    connection => 'my_gdrive_connection',
    format => 'file');

Python

from pyspark import pipelines as dp

@dp.table(
  name="streaming_documents",
  schema="path STRING, size BIGINT, modification_time TIMESTAMP, file FILE MANAGED",
  table_properties={"databricks.filespace-preview": "/Volumes/my_catalog/my_schema/filespace/"}
)
def streaming_documents():
  return (
    spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "file")
      .option("databricks.connection", "my_gdrive_connection")
      .load("https://drive.google.com/drive/folders/my-folder-id")
  )

Aktualisierungen und Löschungen mit AUTO CDC anwenden

Ein Streaming-Ingest fügt neue Dateien hinzu, erfasst aber keine Updates oder Löschungen vom Quellcode. Um diese Änderungen anzuwenden, lies den Quell-Änderungsfeed mit AUTO CDC.

Warning

Databricks empfiehlt, die Änderungsdaten zuerst in einer verwalteten Tabelle zu landen, wie im folgenden Beispiel, und dann auf diese Tabelle anzuwenden AUTO CDC . Das direkte Anwenden von AUTO CDC auf STREAM read_files(..., readChangeFeed => true) liest den Änderungsfeed der Quelle für jeden nachgelagerten Datenfluss erneut, was die Verarbeitungskosten erhöhen könnte.

Verarbeiten Sie den Änderungsfeed in zwei Schritten. Das folgende Beispiel liest den Änderungsfeed aus SharePoint ein und wendet ihn dann als SCD-Typ 1 auf eine Ziel-Streaming-Tabelle an:

Schreiben Sie die Änderungsdaten in eine Streaming-Tabelle mit verwalteten Dateien, wie im folgenden Code. Setzen Sie readChangeFeed => true auf read_files, um den Änderungsfeed zurückzugeben, der die Metadatenspalten _file_id, _sequence und _is_deleted enthält.

SQL

CREATE OR REFRESH STREAMING TABLE documents_changes (
  _file_id STRING,
  _sequence BIGINT,
  _is_deleted BOOLEAN,
  path STRING,
  size BIGINT,
  modification_time TIMESTAMP,
  file FILE MANAGED
)
TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/')
AS SELECT *
  FROM STREAM read_files(
    'https://example.sharepoint.com/sites/my-site/',
    connection => 'my_sharepoint_connection',
    format => 'file',
    readChangeFeed => true);

Python

from pyspark import pipelines as dp

@dp.table(
  name="documents_changes",
  table_properties={"databricks.filespace-preview": "/Volumes/my_catalog/my_schema/filespace/"}
)
def documents_changes():
  return (
    spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "file")
      .option("databricks.connection", "my_sharepoint_connection")
      .option("cloudFiles.readChangeFeed", "true")
      .load("https://example.sharepoint.com/sites/my-site/")
  )

Verwenden Sie AUTO CDC , um die Änderungen aus dieser Tabelle auf eine Ziel-Streaming-Tabelle anzuwenden, wie im folgenden Code. Verwenden Sie _file_id als Schlüssel, _sequence als Sequenzspalte und _is_deleted zum Identifizieren von Löschungen.

SQL

CREATE OR REFRESH STREAMING TABLE documents
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/');

CREATE FLOW documents_cdc AS AUTO CDC INTO
  documents
FROM STREAM documents_changes
  KEYS (_file_id)
  APPLY AS DELETE WHEN _is_deleted = true
  SEQUENCE BY _sequence
  COLUMNS * EXCEPT (_is_deleted, _sequence)
  STORED AS SCD TYPE 1;

Python

from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr

dp.create_streaming_table(
  name="documents",
  table_properties={"databricks.filespace-preview": "/Volumes/my_catalog/my_schema/filespace/"}
)

dp.create_auto_cdc_flow(
  target = "documents",
  source = "documents_changes",
  keys = ["_file_id"],
  sequence_by = col("_sequence"),
  apply_as_deletes = expr("_is_deleted = true"),
  except_column_list = ["_is_deleted", "_sequence"],
  stored_as_scd_type = 1
)

Inline-Binärdaten in FILE-Referenzen umwandeln

Wenn eine Tabelle bereits Dateiinhalte als Inline-Binärdaten speichert, verwenden Sie die create_file Funktion, um diese Daten im Speicher abzulegen und einen FILE Verweis zu erzeugen.

Die folgenden Beispiele verwenden eine benutzerdefinierte Tabelle, raw_documents, mit einer name Spalte und einer Spalte content , die die Binärdaten enthält.

Binärdaten als FILE MANAGED im verwalteten Speicher schreiben

Um die Dateien als verwaltete Dateien zu speichern, rufen Sie create_file nur mit dem Binärinhalt auf. Wenn Sie destination_path weglassen, lädt Unity Catalog den Inhalt an den verwalteten Speicherort hoch:

SQL

CREATE TABLE managed_documents (name STRING, file FILE MANAGED) USING DELTA
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/');

INSERT INTO managed_documents (name, file)
  SELECT name, create_file(content => content)
  FROM raw_documents;

Python

(spark.read.table("raw_documents")
  .selectExpr("name", "create_file(content => content) AS file")
  .writeTo("managed_documents").append())

Scala

spark.read.table("raw_documents")
  .selectExpr("name", "create_file(content => content) AS file")
  .writeTo("managed_documents").append()

Schreibe binäre Daten auf ein Volume als FILE EXTERNAL

Um die Dateien stattdessen als externe Dateien auf ein Unity-Catalog-Volume zu schreiben, ein destination_path an create_file übergeben, wie im folgenden Code:

SQL

CREATE TABLE documents (name STRING, file FILE EXTERNAL) USING DELTA;

INSERT INTO documents (name, file)
  SELECT
    name,
    create_file(
      content => content,
      destination_path => '/Volumes/my_catalog/my_schema/my_volume/' || name
    )
  FROM raw_documents;

Python

(spark.read.table("raw_documents")
  .selectExpr(
    "name",
    "create_file(content => content, destination_path => '/Volumes/my_catalog/my_schema/my_volume/' || name) AS file")
  .writeTo("documents").append())

Scala

spark.read.table("raw_documents")
  .selectExpr(
    "name",
    "create_file(content => content, destination_path => '/Volumes/my_catalog/my_schema/my_volume/' || name) AS file")
  .writeTo("documents").append()

Nächste Schritte

FILE Typ
FILE-Typ und unstrukturierte Daten
Tutorial: Erstellen Sie eine Dateiverarbeitungspipeline mit dem FILE-Typ
Erfahren Sie mehr über das automatische Laden. Siehe Was ist Autoloader?.

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-10-08

Dateien als FILE-Typ eintragen

Speichermodi

Verwenden Sie list_files, um Dateien zu finden

Dateien als FILE-Referenzen eintragen

Externe Quellcodedateien als FILE MANAGED eintragen

SQL

Python

Scala

Volume-Dateien als FILE EXTERNAL einlesen

Verwenden Sie Pipelines, um neue Dateien inkrementell aufzunehmen

SQL

Python

Aktualisierungen und Löschungen mit AUTO CDC anwenden

SQL

Python

SQL

Python

Inline-Binärdaten in FILE-Referenzen umwandeln

Binärdaten als FILE MANAGED im verwalteten Speicher schreiben

SQL

Python

Scala

Schreibe binäre Daten auf ein Volume als FILE EXTERNAL

SQL

Python

Scala

Nächste Schritte

Feedback

Zusätzliche Ressourcen

Verwenden Sie `list_files`, um Dateien zu finden