Tipo de ficheiro e dados não estruturados

Importante

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

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

Com colunas FILE MANAGED, o Unity Catalog armazena cópias dos ficheiros e gere-as através da tabela: ao eliminar linhas, os ficheiros referenciados passam a poder ser recolhidos, pelo que a tabela e os seus ficheiros se mantêm sincronizados.

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

O diagrama seguinte mostra uma coluna FILE denominada video que contém referências a clipes de condução, juntamente com colunas estruturadas como rota, descrição da cena e rótulo de perigo:

Metadados e armazenamento do ficheiro

Para cada linha, o FILE tipo armazena metadados e um link regulado para o ficheiro em armazenamento. Um FILE valor inclui uri, size, content_type, e checksum campos de metadados. As consultas de metadados não requerem leituras completas de ficheiros, melhorando o desempenho das consultas.

Pode passar FILE valores para funções de IA, como ai_parse_document funções, e para funções definidas pelo utilizador (UDFs).

O diagrama seguinte mostra uma coluna gerida FILE de exemplo, contendo metadados de caminho e tamanho e referências aos ficheiros em armazenamento:

Acesso a metadados e conteúdos

Um valor tem duas partes, e o FILE acesso a cada uma é governado de forma diferente:

• Os metadados dos ficheiros (uri, size, content_type, e checksum) são armazenados nos próprios ficheiros de dados da tabela. Qualquer pessoa com SELECT em cima da mesa pode lê-lo.
• O conteúdo dos ficheiros permanece armazenado. Lê-los requer acesso ao ficheiro: READ VOLUME no volume subjacente para FILE EXTERNAL, ou acesso tanto à tabela como ao volume que sustenta o FileSpace para FILE MANAGED.

Converter um valor FILE para BINARY ou STRING, passá-lo a uma função de IA ou UDF e pré-visualizá-lo na tabela de resultados lê o conteúdo dos ficheiros. Como os metadados fazem parte da tabela, o caminho e o tamanho de um ficheiro são visíveis para qualquer pessoa que possa consultar a tabela, mesmo sem acesso ao conteúdo.

Para pré-visualizar ficheiros nos resultados das consultas, consulte Ficheiros de Pré-visualização nas colunas FICHEIRO.

Por que usar FILE em vez de BINARY ou STRING

A tabela seguinte detalha os desafios ao lidar com grandes ficheiros não estruturados com BINARY ou STRING tipos:

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

Somas de verificação

O checksum campo é um token de integridade para os bytes do ficheiro, da forma <prefix>:<digest>. Usa-o para comparar ficheiros ou verificar se nenhum ficheiro mudou. Os leitores ignoram uma soma de verificação com um prefixo não reconhecido.

Nem sempre existe um checksum. 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 com valores em tabela e read_files função com valores em tabela não preenchem a soma de verificação.

O checksum campo utiliza um dos seguintes prefixos:

Prefixo	Codificação do resumo criptográfico	Description
ETAG	Opaque	A eTag do object store para todo o ficheiro. Fornecida literalmente pela loja, usada apenas para comparação de igualdade, e não recomputável.
MD5	Hexágono minúsculo	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	Hexágono minúsculo	Um checksum CRC32C (RFC 3385) com 8 caracteres hexadecimais.
SHA-256	Hexágono minúsculo	Um resumo SHA-256 (RFC 6234), 64 caracteres hexadecimais.

Por exemplo, um checksum MD5 assemelha-se a MD5:d41d8cd98f00b204e9800998ecf8427e, e um eTag de armazenamento de objetos assemelha-se a ETAG:"686897696a7c876b7e", incluindo as aspas duplas à volta devolvidas pelo armazenamento de objetos.

Selecione entre FILE e BINARY

A tabela seguinte compara as opções para trabalhar com ficheiros não estruturados:

Tipo de coluna	Values	Caso de utilização
FILE	Uma referência governada a um ficheiro, mais metadados (uri, size, content_type, checksum).	Utiliza-se para gerir e processar ficheiros não estruturados juntamente com dados estruturados, e para passar ficheiros para funções integradas e de IA.
BINARY	Os bytes brutos de um ficheiro, em linha numa coluna.	Use para objetos pequenos (até 64 KB por defeito) armazenados diretamente no ficheiro de dados. Isto é útil quando precisas de baixa sobrecarga de metadados e uma gestão de ficheiros simplificada. Por exemplo, use isto para armazenar miniaturas em linha com os dados das linhas.

FICHEIRO GERIDO e FICHEIRO EXTERNO

O FILE tipo suporta duas abordagens para gerir os ficheiros:

• FILE MANAGED colunas copiam ficheiros para armazenamento gerido. As permissões são simplificadas e geridas através da tabela. Quando apagas linhas, ou as atualizas para referenciar ficheiros diferentes, os ficheiros não referenciados tornam-se elegíveis para recolha de lixo, para que a tabela e os seus ficheiros permaneçam sincronizados. Use esta abordagem para cargas de trabalho que acedam a ficheiros através de uma tabela, como treino de ML ou geração aumentada por recuperação (RAG), e para ficheiros ingeridos de fontes externas. Para padrões de ingestão, veja Ingerir ficheiros como o tipo FILE.
• FILE EXTERNAL as colunas referenciam ficheiros existentes num volume do Catálogo Unity. Os ficheiros são protegidos pelas permissões de volumes do Unity Catalog, mas o seu ciclo de vida não é gerido pelo Unity Catalog, e não são copiados. Use esta abordagem quando precisar de referenciar ficheiros sem mover dados ou interromper ferramentas que leem de um volume existente.

O Azure Databricks recomenda FILE MANAGED para cargas de trabalho que beneficiam de permissões ao nível de ficheiro e conformidade incorporada: o acesso a cada ficheiro é governado pela tabela que o referencia, e eliminar linhas torna os ficheiros referenciados elegíveis para recolha de lixo. Use FILE EXTERNAL quando os ficheiros têm de permanecer nos seus caminhos de volume existentes para ferramentas que os leem fora da tabela.

Para consultas, não há diferença entre ficheiros geridos e externos.

O diagrama seguinte mostra como o FILE tipo liga o seu código a ficheiros no armazenamento de objetos na cloud:

FILE MANAGED

FILE MANAGED as colunas armazenam cópias de ficheiros num FileSpace, um volume do Unity Catalog que declaras para a tabela usar como armazenamento gerido. O seu ciclo de vida está ligado às tabelas que os referenciam: eliminar linhas torna os ficheiros referenciados elegíveis para recolha de lixo, para que a tabela e os seus ficheiros permaneçam sincronizados.

Os seguintes comportamentos aplicam-se a FILE MANAGED:

• Declarar o FileSpace requer a databricks.filespace-preview propriedade da tabela.
• Ler ou escrever um ficheiro gerido requer acesso à tabela e ao volume subjacente ao FileSpace.
• A recolha automática de lixo de ficheiros não referenciados não é suportada na versão Beta.

Ficheiros não estruturados armazenados em fontes externas como SharePoint, Google Drive, OneDrive e SFTP devem ser ingeridos como ficheiros geridos antes de os poder usar com funções como ai_parse_document funções e funções definidas pelo utilizador (UDFs). Para padrões de ingestão, veja Ingerir ficheiros como sendo do tipo FILE.

Para usar ficheiros geridos, 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:

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

Para exemplos completos, veja os seguintes FILE MANAGED exemplos.

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 de tabela antes de adicionar a coluna, como no seguinte código:

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

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

Falha ao adicionar uma coluna FILE MANAGED a uma tabela sem FileSpace.

Eliminar ficheiros geridos sem referência

Como a recolha automática de lixo não é suportada, apaga os ficheiros sem referência tu próprio. O seguinte notebook encontra os ficheiros num FileSpace que não são referenciados por nenhuma versão da tabela e, opcionalmente, elimina-os:

Bloco de notas da recolha de lixo do FileType

Obter bloco de notas

FILE EXTERNAL

FILE EXTERNAL as colunas são referências a ficheiros que já existem num volume do Unity Catalog.

Se tiver os privilégios necessários no volume, pode atualizar ou eliminar esses ficheiros. O Databricks recomenda que utilize ficheiros imutáveis. Uma permissão na tabela expõe os metadados do ficheiro, mas a leitura dos bytes do ficheiro também requer o privilégio READ VOLUME no volume subjacente.

Um ficheiro externo mapeia cada linha de tabela para um ficheiro no seu caminho existente num 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 ficheiro:

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

Governação e comparação do ciclo de vida

A tabela seguinte compara como FILE MANAGED e FILE EXTERNAL regulam o acesso a ficheiros e gerem o ciclo de vida do ficheiro:

Tipo de coluna	FILE MANAGED	FILE EXTERNAL
Controlo de acesso a ficheiros	Controlado pelas permissões da tabela e do volume, como as SELECT na tabela e READ VOLUME no volume.	Controlado por permissões de volume, como READ VOLUME.
Ciclo de vida e recolha de lixo	Os ficheiros estão ligados às linhas que os referenciam. Eliminar essas linhas torna os ficheiros elegíveis para recolha de lixo. A recolha automática de lixo não é suportada.	Tu geres os ficheiros tu próprio. Eliminar uma linha de tabela não afeta o ficheiro subjacente no volume.

Casos de utilização do tipo FILE

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

Desafio	Tipo suportado FILE	Benefits
Ficheiros demasiado grandes para armazenar em linha como BINARY	FILE MANAGED ou FILE EXTERNAL	Uma FILE coluna armazena uma referência, por isso um ficheiro é lido apenas quando uma função de IA ou UDF o processa. Isto evita que objetos grandes se materializem em linha na mesa.
Ciclo de vida e governação desconectados entre o sistema de ficheiros e a tabela	FILE MANAGED	O Azure Databricks liga o ciclo de vida de cada ficheiro à tabela, por isso eliminar linhas torna os ficheiros elegíveis para limpeza em vez de deixar ficheiros órfãos em armazenamento.
Cargas de trabalho concorrentes que exigem que os ficheiros permaneçam no mesmo local	FILE EXTERNAL	Os ficheiros mantêm-se nos seus caminhos de volume existentes, sem serem afetados pelo ciclo de vida da tabela, por isso outras ferramentas que leem os mesmos ficheiros não são interrompidas.

Passos seguintes

• FILE tipo
• Faça a ingestão de ficheiros como o tipo FILE
• Tutorial: Construa um pipeline de processamento de ficheiros com o tipo FILE
• ai_parse_document Função