Pular para o conteúdo principal
Última atualização em

Ingerir arquivos como o tipo FILE

info

Beta

Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

O tipo FILE armazena e query referências a arquivos não estruturados (documentos, imagens e áudio) em tabelas. Esta página mostra como descobrir arquivos, ingeri-los como referências FILE e ingerir novos arquivos incrementalmente à medida que chegam.

Para a referência sobre o tipo FILE, consulte tipoFILE. Para uma visão geral das abordagens para ingestão de dados não estruturados, consulte Tipo de arquivo FILE e dados não estruturados.

nota

FILE as colunas não têm uma ordenação definida. Você não pode usar uma coluna FILE como coluna de partição, coluna de cluster ou key de Z-order. Para obter mais informações, consulte Limites.

Modos de armazenamento​

Uma referência FILE pode ser armazenada em um dos dois modos:

  • FILE MANAGED armazena cópias de arquivos no armazenamento gerenciado pelo Unity Catalog: as permissões são gerenciadas por meio da tabela, e a exclusão de linhas torna os arquivos referenciados elegíveis para coleta de lixo, para que a tabela e seus arquivos permaneçam sincronizados. Arquivos de fontes fora de volumes, como SharePoint, Google Drive ou SFTP, devem ser ingeridos e armazenados como FILE MANAGED.
  • FILE EXTERNAL faz referência a arquivos que já existem em um volume do Unity Catalog. O Databricks não oferece suporte ao armazenamento de referências FILE EXTERNAL para arquivos armazenados fora de volumes.

A Databricks recomenda FILE MANAGED para cargas de trabalho que se beneficiam de permissões em nível de arquivo e compliance integrada. Para uma comparação de governança e comportamento de ciclo de vida, consulte Tipo FILE e dados não estruturados.

Use list_files para descobrir arquivos​

Utilize a list_files table-valued function para descobrir os arquivos disponíveis em um caminho. Ele retorna uma linha por arquivo com seu path, size, modification_time e uma referência FILE:

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

Para descobrir arquivos em uma origem que requer uma conexão do Unity Catalog, como SharePoint, Google Drive ou SFTP, adicione o parâmetro connection:

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

list_files descobre arquivos recursivamente por default. Para saber mais, consulte a função de valor de tabelalist_files.

Ingerir arquivos como referências de ARQUIVO​

Selecione uma abordagem de ingestão com base em onde você armazena seus arquivos. Para ingerir arquivos de uma origem externa, copie-os para o armazenamento gerenciado como FILE MANAGED. Para referenciar arquivos que já estão em um volume do Unity Catalog sem copiá-los, use FILE EXTERNAL.

Ingerir arquivos de origem externos como FILE GERENCIADO​

Para gerar referências de FILE para arquivos em uma fonte como SharePoint, Google Drive ou SFTP, ingira os arquivos primeiro e armazene-os como FILE MANAGED. FILE EXTERNAL não é compatível com arquivos armazenados fora de volumes.

O exemplo a seguir ingere arquivos do SharePoint em uma tabela FILE 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');

Ingira arquivos de volume como FILE EXTERNAL​

Para inserir arquivos que já existem em um volume do Unity Catalog, use uma instrução CREATE TABLE AS SELECT (CTAS) com list_files. Isso cria uma tabela com uma coluna FILE EXTERNAL que referencia cada arquivo no local, sem copiar seu conteúdo. O exemplo a seguir cria uma tabela documents com o nome do arquivo, metadados e uma referência FILE para cada arquivo:

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

Use pipelines para ingerir novos arquivos incrementalmente​

Para ingerir novos arquivos conforme eles chegam, use uma tabela de transmissão em um LakeFlow Pipelines que lê a origem com STREAM read_files(..., format => 'file'). Cada atualização de pipeline processa apenas os arquivos adicionados após a última atualização. Veja read_files e Spark Declarative Pipelines.

Para fazer a transmissão incremental de arquivos de uma fonte como o Google Drive:

  1. Defina o canal do pipeline como PREVIEW. A ingestão de referências FILE em um pipeline requer o canal PREVIEW.
  2. Defina uma tabela de transmissão que leia a fonte com STREAM read_files(..., format => 'file'), como no código a seguir:
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');

Aplicar atualizações e exclusões com CDC AUTOMÁTICO​

Uma ingestão de transmissão adiciona novos arquivos, mas não captura atualizações ou exclusões da origem. Para aplicar essas alterações, leia o feed de alterações da origem com AUTO CDC.

atenção

O Databricks recomenda que você primeiro grave os dados de alteração em uma tabela gerenciada, como no exemplo a seguir, e depois aplique AUTO CDC a essa tabela. A aplicação de AUTO CDC diretamente em STREAM read_files(..., readChangeFeed => true) relê o feed de alterações de origem para cada fluxo downstream, o que pode aumentar os custos de processamento.

Ingira o feed de alterações em dois passos. O exemplo a seguir ingere o feed de alterações do SharePoint e, em seguida, aplica-o a uma tabela de transmissão de destino como SCD tipo 1:

  1. Grave os dados de alteração em uma tabela de transmissão com arquivos gerenciados, como no código a seguir. Defina readChangeFeed => true em read_files para retornar o feed de alteração, que inclui as colunas de metadados _file_id, _sequence e _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);
  1. Use AUTO CDC para aplicar as alterações dessa tabela a uma tabela de transmissão de destino, como no código a seguir. Use _file_id como a key, _sequence como a coluna de sequência e _is_deleted para identificar exclusões.
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;

Converter dados binários embutidos em referências de FILE​

Se uma tabela já armazenar conteúdos de arquivo como dados binários em linha, use a funçãocreate_file para gravar esses dados no armazenamento e produzir uma referência FILE.

Os exemplos a seguir usam uma tabela gerada pelo usuário, raw_documents, com uma coluna name e uma coluna content que contém os dados binários.

Gravar dados binários no armazenamento gerenciado como FILE MANAGED​

Para armazenar os arquivos como arquivos gerenciados, chame create_file apenas com o conteúdo binário. Quando você omite destination_path, o Unity Catalog faz o upload do conteúdo para o local de armazenamento gerenciado:

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;

Gravar dados binários em um volume como FILE EXTERNAL​

Para gravar os arquivos em um volume do Unity Catalog como arquivos externos, passe um destination_path para create_file, conforme o código a seguir:

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;

Próximos passos​

Nesta página