Use o UniForm para ler as tabelas Delta com clientes Iceberg

O Delta Universal Format (UniForm) permite que o senhor leia tabelas Delta com clientes de leitura Iceberg. Esse recurso requer o Databricks Runtime 14.3 LTS ou superior.

Importante

Para obter a documentação do recurso de tabela UniForm IcebergCompatV1 legado, consulte Legacy UniForm IcebergCompatV1.

O UniForm aproveita o fato de que Delta Lake e Iceberg consistem em arquivos de dados Parquet e uma camada de metadados. O UniForm gera automaticamente metadados Iceberg de forma assíncrona, sem reescrever dados, para que os clientes Iceberg possam ler tabelas Delta como se fossem tabelas Iceberg. Uma única cópia dos arquivos de dados atende a ambos os formatos.

Você pode configurar uma conexão externa para que o Unity Catalog atue como um catálogo Iceberg. Consulte Ler usando o endpointdo catálogo Unity Catalog Iceberg.

O UniForm usa o zstd em vez do snappy como codec de compactação para arquivos de dados Parquet subjacentes.

Observação

Execução de geração de metadados UniForm de forma assíncrona na compute usada para gravar dados em tabelas Delta, o que pode aumentar o uso de recursos do driver.

Requisitos

Para ativar o UniForm, você deve atender aos seguintes requisitos:

A tabela Delta deve ser registrada no Unity Catalog. Ambas as tabelas gerenciais e externas são suportadas.
A tabela deve ter o mapeamento de coluna ativado. Consulte Renomear e descartar colunas com mapeamento de coluna Delta Lake.
A tabela Delta deve ter um minReaderVersion >= 2 e minWriterVersion >= 7. Consulte Como o Databricks gerencia a compatibilidade de recursos do Delta Lake?.
As gravações na tabela devem usar o Databricks Runtime 14.3 LTS ou acima.

Observação

O senhor não pode ativar vetores de exclusão em uma tabela com o UniForm ativado. Ao ativar o UniForm em uma tabela existente com vetores de exclusão ativados, o UniForm desativa e limpa os vetores de exclusão e reescreve os arquivos de dados conforme necessário.

Ativar Delta UniForm

Importante

A ativação do Delta UniForm define o recurso IcebergCompatV2 da tabela Delta, um recurso de protocolo de gravação. Somente os clientes que suportam esse recurso de tabela podem gravar em tabelas habilitadas para UniForm. O senhor deve usar o Databricks Runtime 14.3 LTS ou superior para gravar em tabelas Delta com esse recurso ativado.

Você pode desativar o UniForm desativando a propriedade da tabela delta.universalFormat.enabledFormats . Você não pode desativar o mapeamento de coluna depois de habilitado, e as atualizações para as versões do protocolo de leitor e gravador do Delta Lake não podem ser desfeitas.

O senhor deve definir as seguintes propriedades da tabela para ativar o suporte do UniForm para o Iceberg:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

O senhor também deve ativar o mapeamento de colunas para usar o UniForm. Isso é ativado automaticamente se o senhor ativar o UniForm durante a criação da tabela, como no exemplo a seguir:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

O senhor pode ativar o UniForm em uma tabela existente usando a seguinte sintaxe:

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

Observação

Essa sintaxe também funciona para atualizar a partir da versão Public Preview do UniForm, que usava o recurso de tabela IcebergCompatV1.

Essa sintaxe desativa e elimina automaticamente os vetores de exclusão da tabela. Os arquivos existentes são reescritos conforme necessário para torná-los compatíveis com o Iceberg.

Quando você habilita o UniForm pela primeira vez, a geração de metadados assíncronos começa. Esta tarefa deve ser concluída antes que os clientes externos possam query a tabela usando o Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

Observação

Se você planeja usar o BigQuery como seu cliente de leitor Iceberg, deve definir spark.databricks.delta.write.dataFilesToSubdir como true no Databricks para acomodar um requisito do BigQuery para fornecimento de dados.

Consulte Limitações.

Quando o UniForm gera metadados do Iceberg?

O Databricks aciona a geração de metadados do Iceberg de forma assíncrona depois que uma transação de gravação do Delta Lake é concluída usando a mesma compute que concluiu a transação Delta. Você também pode acionar manualmente a geração de metadados do Iceberg. Consulte Acionar manualmente a conversão de metadados do Iceberg.

Para evitar latências de gravação associadas à geração de metadados Iceberg, as tabelas Delta com commit frequente podem agrupar várias commit Delta em uma única commit Iceberg .

O Delta Lake garante que apenas um processo de geração de metadados Iceberg esteja em andamento a qualquer momento. commit que acionaria um segundo processo concorrente de geração de metadados do Iceberg será commit com sucesso no Delta, mas não acionará a geração assíncrona de metadados do Iceberg. Isso evita a latência em cascata para geração de metadados para cargas de trabalho com commit frequente (segundos a minutos entre commit).

Consulte as versões das mesas Delta e Iceberg.

Verifique o status de geração de metadados do Iceberg

O UniForm adiciona os seguintes campos aos metadados da tabela Unity Catalog e Iceberg para rastrear o status da geração de metadados:

Campo de metadados	Descrição
`converted_delta_version`	A versão mais recente da tabela Delta para a qual os metadados do Iceberg foram gerados com sucesso.
`converted_delta_timestamp`	O carimbo de data/hora do último commit Delta para o qual os metadados do Iceberg foram gerados com sucesso.

No Databricks, o senhor pode revisar esses campos de metadados seguindo um dos seguintes procedimentos:

Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
Revisão dos metadados da tabela com o Catalog Explorer.
Usando a API REST para obter uma tabela.

Consulte a documentação do cliente do leitor Iceberg para saber como revisar as propriedades da tabela fora do Databricks. Para OSS Apache Spark, você pode ver essas propriedades usando a seguinte sintaxe:

SHOW TBLPROPERTIES <table-name>;

Acione manualmente a conversão de metadados do Iceberg

Você pode acionar manualmente a geração de metadados do Iceberg para a versão mais recente da tabela Delta. Esta execução é executada de forma síncrona, ou seja, quando ela for concluída, o conteúdo da tabela disponível no Iceberg refletirá a versão mais recente da tabela Delta disponível quando o processo de conversão começar.

Essas operações não devem ser necessárias em condições normais, mas podem ajudar se você encontrar o seguinte:

Um clusters termina antes que a geração automática de metadados seja bem-sucedida.
Um erro ou falha Job interrompe a geração de metadados.
Um cliente que não oferece suporte à geração de metadados UniForm Iceberg grava na tabela Delta.

Use a seguinte sintaxe para acionar manualmente a geração de metadados do Iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte TABELA DE REPAROS.

Ler usando um caminho JSON de metadados

Alguns clientes Iceberg exigem que você forneça um caminho para arquivos de metadados com versão para registrar tabelas externas do Iceberg. Cada vez que o UniForm converte uma nova versão da tabela Delta em Iceberg, ele cria um novo arquivo JSON de metadados.

Os clientes que usam caminhos JSON de metadados para configurar o Iceberg incluem o BigQuery. Consulte a documentação do cliente do leitor Iceberg para obter detalhes de configuração.

O Delta Lake armazena os metadados do Iceberg no diretório da tabela, usando o seguinte padrão:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

No Databricks, o senhor pode revisar esse local de metadados executando uma das seguintes ações:

Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
Revisão dos metadados da tabela com o Catalog Explorer.
Usando o seguinte comando com a API REST:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

A resposta inclui a seguinte informação:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Importante

Os clientes de leitura Iceberg baseados em caminho podem exigir a atualização manual e a atualização de caminhos JSON de metadados para ler as versões atuais da tabela. Os usuários podem encontrar erros ao consultar tabelas Iceberg usando versões desatualizadas, pois os arquivos de dados Parquet são removidos da tabela Delta com VACUUM.

Leia usando o ponto de extremidade do catálogo Unity Catalog Iceberg

Alguns clientes Iceberg podem se conectar a um catálogo REST Iceberg. Unity Catalog fornece uma implementação somente leitura da API do catálogo REST Iceberg para tabelas Delta com UniForm ativado usando o terminal /api/2.1/unity-catalog/iceberg. Consulte a especificação da API REST do Iceberg para obter detalhes sobre como usar essa API REST.

Os clientes conhecidos por oferecer suporte à API do catálogo Iceberg incluem Apache Spark, Flink e Trino. Você deve configurar o acesso ao armazenamento de objeto cloud subjacente que contém a tabela Delta com UniForm ativado. Consulte a documentação do cliente do leitor Iceberg para obter detalhes de configuração.

Você deve gerar e configurar um access token pessoal do Databricks para permitir que outro serviço se conecte ao Unity Catalog. Consulte Autenticação para automação do Databricks – visão geral.

O seguinte é um exemplo das configurações para configurar o OSS Apache Spark para ler o UniForm como Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

Substitua o URL completo do workspace no qual você gerou os access tokens pessoal para <api-root>.

Observação

Ao consultar tabelas no Unity Catalog usando esse método, os identificadores de objeto usam o seguinte padrão:

unity.<catalog-name>.<schema-name>.<table-name>

Esse padrão usa o mesmo namespace de três camadas presente no Unity Catalog, mas adiciona um prefixo adicional unity.

Versões de mesa Delta e Iceberg

Tanto o Delta Lake quanto o Iceberg permitem query viagem do tempo usando versões de tabela ou registros de data e hora armazenados nos metadados da tabela.

Em geral, as versões das tabelas Iceberg e Delta não se alinham nem pelo carimbo de data/hora do commit nem pelo ID da versão. Se você deseja verificar a qual versão de uma tabela Delta corresponde uma determinada versão de uma tabela Iceberg, você pode usar as propriedades da tabela correspondente definidas na tabela Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

Limitações

Existem as seguintes limitações:

O UniForm não funciona em tabelas com vetores de exclusão ativados. Consulte O que são vetores de exclusão?.
Delta As tabelas com o UniForm ativado não são compatíveis com os tipos VOID.
Os clientes Iceberg só podem ler do UniForm. Gravações não são suportadas.
Os clientes do leitor Iceberg podem ter limitações individuais, independentemente do UniForm. Consulte a documentação do cliente escolhido.
Os destinatários do Delta Sharing só podem ler a tabela como Delta, mesmo quando o UniForm está ativado.

O Change Data Feed funciona para clientes Delta quando o UniForm está ativado, mas não tem suporte no Iceberg.

Alguns recursos de tabela do Delta Lake usados pelo UniForm não são suportados por alguns clientes de leitura do Delta Sharing. Veja Compartilhar dados e IA ativo com segurança usando o Delta Sharing.