Tipo de ARQUIVO e dados não estruturados

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 uma referência governada para um arquivo não estruturado, com metadados como caminho e tamanho. Use colunas FILE no Unity Catalog para armazenar documentos, imagens e áudio junto com dados estruturados.

Para a referência de tipo, consulte tipoFILE.

O diagrama a seguir mostra uma coluna FILE chamada video que referencia clipes de direção juntamente com colunas estruturadas, como rota, descrição da cena e rótulo de perigo:

Metadados e armazenamento de ARQUIVO

Para cada linha, o tipo FILE armazena metadados e um link governado para o arquivo no armazenamento. Um valor FILE inclui os campos de metadados uri, size, content_type e checksum. As queries de metadados não exigem leituras completas de arquivos, melhorando o desempenho de query.

Você pode passar valores FILE para funções de AI, como a funçãoai_parse_document, e para funções definidas pelo usuário (UDFs).

O diagrama a seguir mostra um exemplo de coluna FILE gerenciada, contendo metadados de caminho e tamanho e referências aos arquivos no armazenamento:

Por que usar FILE em vez de BINARY ou STRING

A tabela a seguir detalha os desafios ao lidar com arquivos não estruturados grandes com tipos BINARY ou STRING:

Tipo de coluna	Descrição	Diagrama
BINARY	Materializa o objeto completo para cada leitura, mesmo quando você só precisa de metadados, como o tamanho ou o caminho do arquivo. Isso resulta em computação desnecessária e queries lentas.
STRING	Armazena um caminho de arquivo sem metadados, como informações de tamanho ou versão, e sem link governado entre a tabela e o arquivo. Se outra carga de trabalho remover o arquivo, a tabela terá informações desatualizadas. Se você remover uma linha da tabela, o arquivo referenciado permanecerá no armazenamento até que você o remova manualmente.

Tipo de coluna	Descrição	Diagrama
BINARY	Materializa o objeto completo para cada leitura, mesmo quando você só precisa de metadados, como o tamanho ou o caminho do arquivo. Isso resulta em computação desnecessária e queries lentas.
STRING	Armazena um caminho de arquivo sem metadados, como informações de tamanho ou versão, e sem link governado entre a tabela e o arquivo. Se outra carga de trabalho remover o arquivo, a tabela terá informações desatualizadas. Se você remover uma linha da tabela, o arquivo referenciado permanecerá no armazenamento até que você o remova manualmente.

Somas de verificação

O campo checksum é um token de integridade para os bytes do arquivo, no formato <prefix>:<digest>. Use-o para comparar arquivos ou verificar se um arquivo não foi alterado. Os leitores ignoram uma soma de verificação com um prefixo não reconhecido.

Uma soma de verificação nem sempre está disponível. A funçãoto_file, a funçãocreate_file e a funçãocopy_file preenchem a soma de verificação quando o armazenamento de objetos retorna um ETAG. A funçãolist_files table-valued e a funçãoread_files table-valued não preenchem a soma de verificação.

O campo checksum usa um dos seguintes prefixos:

Prefixo	Codificação de resumo	Descrição
ETAG	Opaco	O eTag do armazenamento de objetos para todo o arquivo. Fornecido verbatim pelo armazenamento, usado apenas para comparação de igualdade e não recomputável.
MD5	Hexadecimal em minúsculas	Um resumo MD5 (RFC 1321), 32 caracteres hexadecimais.
CRC32	Hexadecimal em minúsculas	Uma soma de verificação CRC32 (RFC 2083), 8 caracteres hexadecimais.
CRC32C	Hexadecimal em minúsculas	Um checksum CRC32C (RFC 3385), 8 caracteres hexadecimais.
SHA-256	Hexadecimal em minúsculas	Um resumo SHA-256 (RFC 6234), 64 caracteres hexadecimais.

Prefixo	Codificação de resumo	Descrição
ETAG	Opaco	O eTag do armazenamento de objetos para todo o arquivo. Fornecido verbatim pelo armazenamento, usado apenas para comparação de igualdade e não recomputável.
MD5	Hexadecimal em minúsculas	Um resumo MD5 (RFC 1321), 32 caracteres hexadecimais.
CRC32	Hexadecimal em minúsculas	Uma soma de verificação CRC32 (RFC 2083), 8 caracteres hexadecimais.
CRC32C	Hexadecimal em minúsculas	Um checksum CRC32C (RFC 3385), 8 caracteres hexadecimais.
SHA-256	Hexadecimal em minúsculas	Um resumo SHA-256 (RFC 6234), 64 caracteres hexadecimais.

Por exemplo, uma soma de verificação MD5 tem a aparência de MD5:d41d8cd98f00b204e9800998ecf8427e, e um eTag de armazenamento de objetos tem a aparência de ETAG:"686897696a7c876b7e", incluindo as aspas duplas circundantes retornadas pelo armazenamento de objetos.

Selecione entre FILE e BINARY

A tabela a seguir compara as opções para trabalhar com arquivos não estruturados:

Tipo de coluna	Valores	Caso de uso
FILE	Uma referência governada a um arquivo, além de metadados (uri, size, content_type, checksum).	Use para gerenciar e processar arquivos não estruturados juntamente com dados estruturados, e para passar arquivos para funções integradas e de AI.
BINARY	Os bytes brutos de um arquivo, em linha em uma coluna.	Use para objetos pequenos (até 64 KB por default) armazenados diretamente no arquivo de dados. Isso é útil quando você precisa de baixa sobrecarga de metadados e gerenciamento de arquivos simplificado. Por exemplo, use isso para armazenar miniaturas em linha com os dados da linha.

Tipo de coluna	Valores	Caso de uso
FILE	Uma referência governada a um arquivo, além de metadados (uri, size, content_type, checksum).	Use para gerenciar e processar arquivos não estruturados juntamente com dados estruturados, e para passar arquivos para funções integradas e de AI.
BINARY	Os bytes brutos de um arquivo, em linha em uma coluna.	Use para objetos pequenos (até 64 KB por default) armazenados diretamente no arquivo de dados. Isso é útil quando você precisa de baixa sobrecarga de metadados e gerenciamento de arquivos simplificado. Por exemplo, use isso para armazenar miniaturas em linha com os dados da linha.

FILE EXTERNAL e FILE gerenciado

O tipo FILE oferece suporte a duas abordagens para o gerenciamento dos arquivos:

• FILE EXTERNAL colunas referenciam arquivos existentes em um volume do Unity Catalog. Os arquivos são protegidos por permissões de volume do Unity Catalog, mas seu ciclo de vida não é gerenciado pelo Unity Catalog e eles não são copiados. Use esta abordagem quando precisar referenciar arquivos sem mover dados ou interromper ferramentas que leem de um volume existente.
• FILE MANAGED colunas copiam arquivos para o armazenamento gerenciado. Defina a propriedade de tabela databricks.filespace-preview para um caminho de volume gerenciado para o Unity Catalog usar como armazenamento. Use esta abordagem quando desejar permissões simplificadas que sejam gerenciadas por meio da tabela para cargas de trabalho que acessam arquivos apenas por meio de uma tabela, como treinamento de ML ou geração aumentada de recuperação (RAG). Para padrões de ingestão, consulte Ingerir arquivos como o tipo FILE.

Para queries, não há diferença entre arquivos externos e gerenciados.

O diagrama a seguir mostra como o tipo FILE conecta seu código a arquivos no armazenamento de objetos na cloud:

FILE EXTERNAL

FILE EXTERNAL colunas são referências a arquivos que já existem em um volume do Unity Catalog.

Se você tiver os privilégios necessários no volume, poderá atualizar ou excluir esses arquivos. O Databricks recomenda o uso de arquivos imutáveis. Uma concessão de tabela expõe os metadados do arquivo, mas a leitura dos bytes do arquivo também requer o privilégio READ VOLUME no volume subjacente.

Um arquivo externo mapeia cada linha da tabela para um arquivo em seu caminho existente em um volume do Unity Catalog:

FILE EXTERNAL exemplos

Para criar uma tabela com uma coluna FILE EXTERNAL:

SQL

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

Para adicionar uma coluna FILE EXTERNAL a uma tabela existente:

SQL

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

Para criar e popular uma tabela a partir de um volume, atribuindo IDs exclusivos a cada arquivo:

SQL

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

FILE MANAGED

FILE MANAGED colunas armazenam cópias de arquivos em um FileSpace, um volume do Unity Catalog que você declara para a tabela usar como armazenamento gerenciado. O ciclo de vida delas está vinculado às tabelas que as referenciam.

Os seguintes comportamentos se aplicam a FILE MANAGED:

• A declaração de FileSpace requer a propriedade de tabela databricks.filespace-preview.
• A leitura ou gravação de um arquivo gerenciado requer acesso tanto à tabela quanto ao volume que suporta o FileSpace.
• A coleta de lixo automática de arquivos não referenciados não é suportada.

Arquivos não estruturados armazenados em fontes externas, como SharePoint, Google Drive, OneDrive e SFTP, devem ser ingeridos como arquivos gerenciados antes que você possa usá-los com funções como funçãoai_parse_document e funções definidas pelo usuário (UDFs). Para padrões de ingestão, consulte Ingerir arquivos como o tipo FILE.

Para usar arquivos gerenciados, crie uma tabela com uma coluna FILE MANAGED e declare um volume como FileSpace definindo a propriedade de tabela databricks.filespace-preview para um caminho de volume:

Text

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

Para exemplos completos, consulte os seguintes exemplos de FILE MANAGED. O ciclo de vida dos arquivos em um FileSpace está vinculado às linhas que os referenciam. A exclusão dessas linhas torna os arquivos elegíveis para coleta de lixo.

FILE MANAGED exemplos

Para criar uma tabela com uma coluna FILE MANAGED:

SQL

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

Para adicionar uma coluna FILE MANAGED a uma tabela existente, defina a propriedade de tabela databricks.filespace-preview antes de adicionar a coluna, conforme o código a seguir:

SQL

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

Adicionar uma coluna FILE MANAGED a uma tabela que não possui FileSpace falha.

Comparação de governança e ciclo de vida

A tabela a seguir compara como FILE EXTERNAL e FILE MANAGED governam o acesso a arquivos e gerenciam o ciclo de vida dos arquivos:

Tipo da coluna	FILE EXTERNAL	FILE MANAGED
Controle de acesso a arquivos	Regido por permissões de volume, como READ VOLUME.	Regido por permissões de tabela e volume, como SELECT na tabela e READ VOLUME no volume.
Ciclo de vida e coleta de lixo	Você gerencia arquivos por conta própria. A exclusão de uma linha de tabela não afeta o arquivo subjacente no volume.	Os arquivos estão vinculados às linhas que os referenciam. A exclusão dessas linhas torna os arquivos elegíveis para a coleta de lixo. A coleta de lixo automática não é suportada.

Tipo da coluna	FILE EXTERNAL	FILE MANAGED
Controle de acesso a arquivos	Regido por permissões de volume, como READ VOLUME.	Regido por permissões de tabela e volume, como SELECT na tabela e READ VOLUME no volume.
Ciclo de vida e coleta de lixo	Você gerencia arquivos por conta própria. A exclusão de uma linha de tabela não afeta o arquivo subjacente no volume.	Os arquivos estão vinculados às linhas que os referenciam. A exclusão dessas linhas torna os arquivos elegíveis para a coleta de lixo. A coleta de lixo automática não é suportada.

Casos de uso de tipo de arquivo

Ambos os tipos de FILE externos e gerenciados abordam os seguintes desafios para casos de uso que utilizam dados não estruturados:

Desafio	Tipo de FILE compatível	Benefícios
Arquivos grandes demais para armazenar em linha como BINARY	FILE MANAGED ou FILE EXTERNAL	Uma coluna FILE armazena uma referência, portanto, um arquivo é lido somente quando uma função de AI ou UDF o processa. Isso evita a materialização de objetos grandes em linha na tabela.
Ciclo de vida e governança desconectados entre o sistema de arquivos e a tabela	FILE MANAGED	O Databricks vincula o ciclo de vida de cada arquivo à tabela, portanto, a exclusão de linhas torna os arquivos elegíveis para limpeza, em vez de deixar arquivos órfãos no armazenamento.
Workloads concorrentes que exigem que os arquivos permaneçam no mesmo local	FILE EXTERNAL	Os arquivos permanecem em seus caminhos de volume existentes, não afetados pelo ciclo de vida da tabela, portanto, outras ferramentas que leem os mesmos arquivos não são interrompidas.

Desafio	Tipo de FILE compatível	Benefícios
Arquivos grandes demais para armazenar em linha como BINARY	FILE MANAGED ou FILE EXTERNAL	Uma coluna FILE armazena uma referência, portanto, um arquivo é lido somente quando uma função de AI ou UDF o processa. Isso evita a materialização de objetos grandes em linha na tabela.
Ciclo de vida e governança desconectados entre o sistema de arquivos e a tabela	FILE MANAGED	O Databricks vincula o ciclo de vida de cada arquivo à tabela, portanto, a exclusão de linhas torna os arquivos elegíveis para limpeza, em vez de deixar arquivos órfãos no armazenamento.
Workloads concorrentes que exigem que os arquivos permaneçam no mesmo local	FILE EXTERNAL	Os arquivos permanecem em seus caminhos de volume existentes, não afetados pelo ciclo de vida da tabela, portanto, outras ferramentas que leem os mesmos arquivos não são interrompidas.

Próximos passos

• FILE Tipo
• Ingerir arquivos como o tipo FILE
• Tutorial: criar um pipeline de processamento de arquivos com o tipo FILE
• ai_parse_document função