Tipo de arquivo e dados não estruturados

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

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.

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:

Uma tabela de clipes de condução onde a coluna de vídeo é do tipo FILE. Cada linha emparelha colunas estruturadas (ID do clipe, rota, descrição da cena, etiqueta de perigo e um embedding) com uma referência de arquivo de vídeo que mostra uma miniatura e um tamanho como 1,8 GB.

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:

A tabela de clipes com a coluna de vídeo armazenada como um tipo FILE, mostrada como um par de caminho e tamanho. Setas vinculam cada linha ao seu arquivo armazenado, ilustrando uma referência governada entre a tabela e os arquivos.

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. A tabela de clipes com a coluna de vídeo armazenada como BANÁRIO. Os bytes brutos de cada vídeo de vários gigabytes são materializados em linha na coluna.
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. A tabela de clipes com a coluna de vídeo armazenada como um caminho STRING, como s3://.../NW-0142. Um caminho não resolve mais para um arquivo no volume, mostrando que caminhos de string não garantem a existência de arquivos e que a governança não está vinculada.

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:

prefixo Codificação digest Description
ETAG Opaque A eTag do object store para todo o arquivo. Fornecido literalmente pela loja, usado apenas para comparação de igualdade, e não recomputável.
MD5 Hexágono minúsculo Um resumo MD5 (RFC 1321), 32 caracteres hexagonais.
CRC32 Hexágono minúsculo Um checksum CRC32 (RFC 2083), 8 caracteres hexadecimais.
CRC32C Hexágono minúsculo Um checksum CRC32C (RFC 3385), 8 caracteres hexadecimais.
SHA-256 Hexágono minúsculo Um digest SHA-256 (RFC 6234), 64 caracteres hexadecimais.

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:

Tipo de coluna Values Caso de uso
FILE Uma referência governada a um arquivo, mais metadados (uri, size, content_type, checksum). Use para gerenciar e processar arquivos não estruturados junto com dados estruturados, além de passar arquivos para funções integradas e de IA.
BINARY Os bytes brutos de um arquivo, em linha em uma coluna. Use para objetos pequenos (até 64 KB por padrão) 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 alinhadas com os dados da linha.

FILE EXTERNAL e FILE MANAGED

O FILE tipo suporta duas abordagens para gerenciar os arquivos:

  • 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.
  • FILE MANAGED Colunas copiam arquivos para armazenamento gerenciado. Defina a databricks.filespace-preview propriedade da tabela para um caminho de volume gerenciado para o Unity Catalog usar como armazenamento. Use essa abordagem quando quiser permissões simplificadas que sejam gerenciadas pela tabela para cargas de trabalho que acessam arquivos apenas por meio de uma tabela, como treinamento de ML ou geração aumentada por recuperação (RAG). Para padrões de ingestão, veja arquivos Ingest como o tipo FILE.

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

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

Diagrama da arquitetura do tipo FILE. Interfaces de cliente como Python, SQL, Scala e UDFs funcionam com um único tipo de FILE que suporta carregamento preguiçoso. O tipo possui duas variações: FILE EXTERNAL, onde o sistema de arquivos gerencia o ciclo de vida, e FILE MANAGED, onde o UC otimiza a governança por meio da tabela. Arquivos externos mapeiam para um volume externo que é governado no nível de volume, e arquivos gerenciados mapeiam para um FileSpace que é governado no nível da tabela, tanto em armazenamento de objetos em nuvem como S3, ADLS ou Google Cloud Storage.

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:

Um diagrama de um volume UC contendo arquivos de teste organizados sob pastas de fase, mapeado para uma coluna EXTERNAL FILE. Cada linha da tabela referencia um arquivo pelo caminho do volume e adiciona colunas estruturadas como Coorte e Fase de Estudo.

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/');

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. Seu ciclo de vida está atrelado às tabelas que os referenciam.

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.

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 . O ciclo de vida dos arquivos em um FileSpace está atrelado às linhas que os referenciam. Deletar essas linhas torna os arquivos elegíveis para coleta de lixo.

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.

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

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

Tipo de 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 os arquivos sozinho. Deletar uma linha de tabela não afeta o arquivo subjacente no volume. Os arquivos estão vinculados às linhas que os referenciam. Deletar essas linhas torna os arquivos elegíveis para coleta de lixo. Coleta automática de lixo não é suportada.

Casos de uso do tipo FILE

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

Desafio Tipo suportado FILE Benefits
Arquivos grandes demais para serem armazenados em linha como BINARY FILE MANAGED ou FILE EXTERNAL Uma FILE coluna armazena uma referência, então um arquivo é lido somente quando uma função de IA ou UDF o processa. Isso evita que objetos grandes se materializem em linha na mesa.
Ciclo de vida e governança desconectados entre o sistema de arquivos e a tabela FILE MANAGED O Azure Databricks vincula o ciclo de vida de cada arquivo à tabela, então excluir linhas torna os arquivos elegíveis para limpeza em vez de deixar arquivos órfãos no armazenamento.
Cargas de trabalho simultâneas que exigem que os arquivos permaneçam no mesmo local FILE EXTERNAL Os arquivos permanecem em seus caminhos de volume existentes, sem ser afetados pelo ciclo de vida da tabela, então outras ferramentas que leem os mesmos arquivos não são interrompidas.

Próximas Etapas 

  • Last updated on