Tipo de arquivo e dados não estruturados

O FILE tipo armazena uma referência governada a um arquivo não estruturado, com metadados como caminho e tamanho. Use FILE colunas no Unity Catalog para armazenar documentos, imagens e áudio junto com dados estruturados.

Com FILE MANAGED as colunas, o Unity Catalog armazena cópias dos arquivos e os gerencia com a tabela: excluir linhas torna os arquivos referenciados elegíveis para coleta de lixo, para que a tabela e seus arquivos permaneçam sincronizados.

Para a referência tipográfica, veja FILE tipo.

O diagrama a seguir mostra uma FILE coluna chamada video que faz referência a clipes de direção ao lado de colunas estruturadas, como rota, descrição da cena e etiqueta de perigo:

Metadados e armazenamento de FILE

Para cada linha, o FILE tipo armazena metadados e um link governado para o arquivo armazenado. Um FILE valor inclui uri, size, content_type, e checksum campos de metadados. Consultas de metadados não exigem leituras completas de arquivos, melhorando o desempenho das consultas.

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

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

Por que usar FILE em vez de BINARY ou STRING

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

Tipo de coluna	Description	Diagrama
BINARY	Materializa o objeto completo a cada leitura, mesmo quando você só precisa de metadados como tamanho ou caminho do arquivo. Isso resulta em cálculos desnecessários e consultas lentas.
STRING	Armazena um caminho de arquivo sem metadados, como informações de tamanho ou versão, e sem ligação governada entre a tabela e o arquivo. Se outra carga de trabalho remove o arquivo, a tabela tem informações obsoletas. Se você remover uma linha de tabela, o arquivo referenciado permanece armazenado até que você o remova manualmente.

Somas de verificação

O checksum campo é um token de integridade para os bytes do arquivo, da forma <prefix>:<digest>. Use para comparar arquivos ou verificar se um arquivo não mudou. Leitores ignoram uma soma de verificação com prefixo não reconhecido.

Nem sempre há uma soma de verificação disponível. to_file função, create_file função e copy_file função preenchem a soma de verificação quando o armazenamento de objetos retorna um ETAG. list_files Função de tabela e read_files função de tabela não preenchem a soma de verificação.

O checksum campo usa um dos seguintes prefixos:

Por exemplo, um checksum MD5 se parece com MD5:d41d8cd98f00b204e9800998ecf8427e, e um eTag de armazenamento de objetos parece ETAG:"686897696a7c876b7e", incluindo as aspas duplas ao redor 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:

FILE MANAGED e FILE EXTERNAL

O FILE tipo suporta duas abordagens para gerenciar os arquivos:

• FILE MANAGED Colunas copiam arquivos para armazenamento gerenciado. As permissões são simplificadas e gerenciadas pela tabela. Quando você exclui linhas, ou as atualiza para referenciar arquivos diferentes, os arquivos não referenciados tornam-se elegíveis para coleta de lixo, assim a tabela e seus arquivos permanecem sincronizados. Use essa abordagem para cargas de trabalho que acessam arquivos por meio de uma tabela, como treinamento de ML ou geração aumentada por recuperação (RAG), e para arquivos ingeridos de fontes externas. Para padrões de ingestão, veja arquivos Ingest como o tipo FILE.
• FILE EXTERNAL colunas referenciam arquivos existentes em um volume do Catálogo Unity. Os arquivos são protegidos pelas 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 essa abordagem quando precisar referenciar arquivos sem mover dados ou interromper ferramentas que leem de um volume existente.

O Azure Databricks recomenda FILE MANAGED para cargas de trabalho que se beneficiam de permissões em nível de arquivo e conformidade embutida: o acesso a cada arquivo é regido pela tabela que o referencia, e a exclusão de linhas torna os arquivos referenciados elegíveis para coleta de lixo. Use FILE EXTERNAL quando os arquivos precisam permanecer em seus caminhos de volume existentes para ferramentas que os leem fora da tabela.

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

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

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 deles está atrelado às tabelas que os referenciam: excluir linhas torna os arquivos referenciados elegíveis para coleta de lixo, para que a tabela e seus arquivos permaneçam sincronizados.

Os seguintes comportamentos se aplicam a FILE MANAGED:

• Declarar o FileSpace requer a databricks.filespace-preview propriedade da tabela.
• Ler ou escrever um arquivo gerenciado requer acesso tanto à tabela quanto ao volume que suporta o FileSpacearquivo .
• Coleta automática de lixo de arquivos sem referência não é suportada no Beta.

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 ai_parse_document funções e funções definidas pelo usuário (UDFs). Para padrões de ingestão, veja arquivos Ingest como o tipo FILE.

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

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

Para exemplos completos, veja os exemplos a seguir FILE MANAGED .

FILE MANAGED Exemplos

Para criar uma tabela com uma FILE MANAGED coluna:

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

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

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 FILE MANAGED coluna a uma tabela que não FileSpace tem falhas.

Exclua arquivos gerenciados sem referência

Como a coleta automática de lixo não é suportada, delete os arquivos sem referência você mesmo. O seguinte caderno encontra os arquivos em um FileSpace que nenhuma versão da tabela referencia, e opcionalmente os deleta:

Caderno de coleta de lixo FileType

Obter laptop

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, pode atualizar ou excluir esses arquivos. O Databricks recomenda que você use arquivos imutáveis. Uma concessão de tabela expõe os metadados do arquivo, mas ler os bytes do arquivo também requer o READ VOLUME privilégio sobre o volume subjacente.

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

FILE EXTERNAL Exemplos

Para criar uma tabela com uma FILE EXTERNAL coluna:

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

Para adicionar uma FILE EXTERNAL coluna a uma tabela existente:

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

Para criar e preencher uma tabela a partir de um volume, atribuindo IDs únicos a cada arquivo:

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

Governança e comparação do ciclo de vida

A tabela a seguir compara como FILE MANAGED e FILE EXTERNAL governam o acesso a arquivos e lidam com o ciclo de vida do arquivo:

Casos de uso do tipo FILE

Tanto os tipos gerenciados quanto externos FILE enfrentam os seguintes desafios para casos de uso usando dados não estruturados:

Próximas Etapas 

• FILE tipo
• Ingeste arquivos como o tipo FILE
• Tutorial: Construa um pipeline de processamento de arquivos com o tipo FILE
• ai_parse_document função