Importuj pliki jako typ FILE

Important

Ta funkcja jest dostępna w wersji beta.

Typ FILE przechowuje i zapytuje odniesienia do nieustrukturyzowanych plików (dokumentów, obrazów i dźwięków) w tabelach. Na tej stronie pokazano, jak wyszukiwać pliki, importować je jako odwołania FILE oraz przyrostowo importować nowe pliki w miarę ich pojawiania się.

Informacje o typie FILE można znaleźć w temacie typ FILE. Aby uzyskać przegląd podejść do pozyskiwania danych niestrukturalnych, zobacz TYP pliku i dane niestrukturalne.

Uwaga / Notatka

FILE Kolumny nie mają określonego porządku. Nie można użyć kolumny FILE jako kolumny partycjonującej, klasterizacyjnej ani klucza Z-order. Aby uzyskać więcej informacji, zobacz Limity.

Tryby przechowywania

Referencja FILE może być przechowywana w jednym z dwóch trybów:

FILE MANAGED przechowuje kopie plików w magazynie zarządzanym przez Unity Catalog: uprawnienia są zarządzane przez tabelę, a usunięcie wierszy sprawia, że pliki, do których się odwołują, kwalifikują się do usuwania nieużywanych danych, dzięki czemu tabela i jej pliki pozostają zsynchronizowane. Pliki ze źródeł spoza woluminów, takich jak SharePoint, Google Drive czy SFTP, muszą być pobierane i przechowywane jako FILE MANAGED.
FILE EXTERNAL odnosi się do plików, które już istnieją w woluminie Unity Catalog. Databricks nie obsługuje przechowywania referencji FILE EXTERNAL do plików przechowywanych poza woluminami.

Azure Databricks zaleca FILE MANAGED do obsługi obciążeń, które korzystają z uprawnień na poziomie plików i wbudowanej zgodności. Porównanie zarządzania i zachowania cyklu życia znajdziesz w typie FILE oraz danych nieustrukturyzowanych.

Użyj `list_files` do odkrywania plików

Użyj list_files funkcji tabelowej o wartości tabelowej , aby odnaleźć pliki dostępne na danej ścieżce. Zwraca jeden wiersz dla każdego pliku zawierający jego path, size, modification_time oraz odwołanie FILE:

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

Aby odkryć pliki w źródle wymagającym połączenia z Unity Catalog, takim jak SharePoint, Google Drive lub SFTP, dodaj parametr:connection

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

list_files domyślnie wykrywa pliki rekurencyjnie. Aby dowiedzieć się więcej, zobacz list_files funkcję tabelową.

Importuj pliki jako referencje FILE

Wybierz metodę importowania na podstawie miejsca przechowywania plików. Aby pobrać pliki z zewnętrznego źródła, skopiuj je do zarządzanej pamięci masowej jako FILE MANAGED. Aby odwołać się do plików już znajdujących się w wolumenie katalogu Unity bez ich kopiowania, użyj FILE EXTERNAL.

Importuj pliki źródłowe z zewnętrznego źródła jako FILE MANAGED

Aby generować odwołania FILE do plików ze źródła takiego jak SharePoint, Google Drive lub SFTP, najpierw zaimportuj te pliki i przechowuj je jako FILE MANAGED. FILE EXTERNAL nie jest obsługiwany w przypadku plików przechowywanych poza woluminach.

Poniższy przykład pobiera pliki z SharePoint do tabeliFILE MANAGED:

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

Importuj pliki woluminów jako PLIK ZEWNĘTRZNY

Aby pozyskać dane z plików, które już istnieją w woluminie Unity Catalog, użyj instrukcji CREATE TABLE AS SELECT (CTAS) z list_files. Tworzy to tabelę z kolumną FILE EXTERNAL , która odwołuje się do każdego pliku w miejscu, bez kopiowania jego treści. Poniższy przykład tworzy tabelę documents z nazwą pliku, metadanymi oraz referencjami FILE dla każdego pliku:

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

Używaj potoków do stopniowego pobierania nowych plików

Aby pobierać nowe pliki w momencie ich pojawiania się, użyj tabeli strumieniowej w potoku Lakeflow, która odczytuje źródło za pomocą STREAM read_files(..., format => 'file'). Każda aktualizacja potoku przetwarza tylko pliki dodane po ostatniej aktualizacji. Zobacz read_files i Spark Declarative Pipelines na Lakeflow.

Aby stopniowo przesyłać pliki ze źródła takiego jak Google Drive:

Ustaw kanał potoku na PREVIEW. Pobieranie FILE referencji w potoku wymaga kanału PREVIEW .

Zdefiniuj tabelę strumieniową, która odczytuje źródło za pomocą STREAM read_files(..., format => 'file'), jak w następującym kodzie:

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

Stosuj aktualizacje i usuwanie z AUTO CDC

Pobieranie streamingu dodaje nowe pliki, ale nie rejestruje aktualizacji ani usuwań ze źródła. Aby zastosować te zmiany, odczytaj źródłowy strumień zmian za pomocą AUTO CDC.

Ostrzeżenie

Databricks zaleca, aby najpierw umieścić dane zmiany w tabeli zarządzanej, jak w poniższym przykładzie, a następnie zastosować je AUTO CDC do tej tabeli. Zastosowanie AUTO CDC bezpośrednio do STREAM read_files(..., readChangeFeed => true) powoduje ponowny odczyt źródłowego strumienia zmian dla każdego przepływu podrzędnego, co może zwiększyć koszty przetwarzania.

Pozyskanie kanału zmian odbywa się w dwóch krokach. Poniższy przykład wczytuje strumień zmian z SharePoint, a następnie zastosowuje go do docelowej tabeli strumieniowej jako SCD typu 1:

Zapisz dane zmiany do tabeli streamingowej z plikami zarządzanymi, jak w poniższym kodzie. Ustaw readChangeFeed => true na read_files, aby zwrócić kanał informacyjny zmian, który zawiera kolumny metadanych _file_id, _sequence i _is_deleted.

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/")
  )

Użyj AUTO CDC, aby zastosować zmiany z tej tabeli do docelowej tabeli strumieniowej, jak w poniższym przykładzie kodu. Użyj _file_id jako klucza, _sequence jako kolumny sekwencji, a _is_deleted do identyfikowania usunięć.

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
)

Konwertowanie danych binarnych w linii na odniesienia do PLIKU

Jeśli tabela już przechowuje zawartość pliku jako dane binarne w linii, użyj create_file funkcji do zapisu tych danych na pamięć i wygenerowania referencji FILE .

Poniższe przykłady wykorzystują tabelę generowaną przez użytkownika, raw_documents, z kolumną name i kolumną content zawierającą dane binarne.

Zapisz dane binarne do zarządzanej pamięci jako FILE MANAGED

Aby przechowywać pliki jako zarządzane, wywołaj create_file tylko z zawartością binarną. Gdy pominiesz destination_path, Unity Catalog przesyła zawartość do zarządzanej lokalizacji pamięci masowej:

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

Zapisz dane binarne do woluminu jako FILE EXTERNAL

Aby zamiast tego zapisać pliki w woluminie katalogu Unity jako pliki zewnętrzne, przekaż destination_path do create_file, zgodnie z poniższym kodem:

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

Następne kroki

FILE typ
Typ pliku i dane nieustrukturyzowane
Samouczek: Zbuduj potok przetwarzania plików z typem PLIKU
Dowiedz się więcej o automatycznym ładowaniu. Zobacz Co to jest moduł automatycznego ładowania?.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-10-08

Importuj pliki jako typ FILE

Tryby przechowywania

Użyj list_files do odkrywania plików

Importuj pliki jako referencje FILE

Importuj pliki źródłowe z zewnętrznego źródła jako FILE MANAGED

SQL

Python

Scala

Importuj pliki woluminów jako PLIK ZEWNĘTRZNY

Używaj potoków do stopniowego pobierania nowych plików

SQL

Python

Stosuj aktualizacje i usuwanie z AUTO CDC

SQL

Python

SQL

Python

Konwertowanie danych binarnych w linii na odniesienia do PLIKU

Zapisz dane binarne do zarządzanej pamięci jako FILE MANAGED

SQL

Python

Scala

Zapisz dane binarne do woluminu jako FILE EXTERNAL

SQL

Python

Scala

Następne kroki

Opinia

Dodatkowe zasoby

Użyj `list_files` do odkrywania plików