Compartilhar via

Ler tabelas Delta com clientes Iceberg

  • Artigo

Este artigo fornece detalhes para habilitar leituras em Iceberg em tabelas armazenadas com Delta Lake no Azure Databricks. Esse recurso requer o Databricks Runtime 14.3 LTS ou superior.

Observação

Essa funcionalidade era anteriormente chamada de Formato Universal do Delta Lake (UniForm).

Você pode configurar uma conexão externa para que o Catálogo do Unity atue como um catálogo do Iceberg. Confira Ler tabelas do Databricks de clientes do Iceberg.

Como funcionam as leituras do Iceberg (UniForm)?

Delta Lake e Iceberg consistem em arquivos de dados Parquet e uma camada de metadados. ** Habilitar leituras do Iceberg configura suas tabelas para gerar automaticamente metadados do Iceberg de forma assíncrona, sem reescrever dados, para que os clientes Iceberg possam ler tabelas Delta escritas pelo Azure Databricks. Uma única cópia dos arquivos de dados serve a vários formatos.

Importante

  • Tabelas com leituras do Iceberg habilitadas usam Zstandard em vez de Snappy como codec de compactação para arquivos Parquet subjacentes.
  • A geração de metadados do Iceberg é executada de modo assíncrono na computação usada para gravar dados em tabelas Delta, o que pode aumentar o emprego de recursos do driver.
  • Para obter a documentação do recurso de tabela UniForm IcebergCompatV1 herdado, confira UniForm IcebergCompatV1 herdado.

Requisitos

Para habilitar as leituras do Iceberg, os seguintes requisitos devem ser atendidos:

Observação

Você não pode habilitar vetores de exclusão em uma tabela com leituras de Iceberg habilitadas.

Use REORG para desabilitar e limpar vetores de exclusão ao habilitar leituras do Iceberg em uma tabela existente com vetores de exclusão habilitados. Consulte Habilitar ou atualizar o suporte de leitura do Iceberg usando o REORG.

Habilitar as leituras do Iceberg (UniForm)

Importante

Quando você habilita as leituras do Iceberg, o recurso de protocolo de gravação IcebergCompatV2 é adicionado à tabela. Somente os clientes que dão suporte a esse recurso de tabela podem gravar em tabelas com leituras de Iceberg habilitadas. No Azure Databricks, você deve usar o Databricks Runtime 14.3 LTS ou superior para gravar em tabelas habilitadas.

Você pode desativar as leituras do Iceberg removendo a propriedade da tabela delta.universalFormat.enabledFormats. As atualizações para as versões do protocolo de leitura e de escrita do Delta Lake não podem ser desfeitas.

Você deve definir as seguintes propriedades de tabela para habilitar as leituras do Iceberg:

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

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

Para obter uma lista de limitações, consulte Limitações.

Habilitar leituras do Iceberg durante a criação da tabela

O mapeamento de colunas deve estar habilitado para usar as leituras do Iceberg. Isso ocorrerá automaticamente se você habilitar as leituras do Iceberg durante a criação da tabela, como no exemplo a seguir:

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

Habilitar as leituras do Iceberg em uma tabela existente

No Databricks Runtime 15.4 LTS e posteriores, você pode habilitar ou atualizar as leituras do Iceberg em uma tabela existente usando a seguinte sintaxe:

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Habilitar ou atualizar o suporte de leitura do Iceberg usando REORG

Você pode usar REORG para habilitar leituras do Iceberg e reescrever arquivos de dados subjacentes, como no exemplo a seguir:

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

Use REORG se qualquer uma das seguintes opções for verdadeira:

  • Sua tabela tem vetores de exclusão habilitados.
  • Você habilitou anteriormente a versão IcebergCompatV1 do UniForm Iceberg.
  • Você precisa ler de mecanismos Iceberg que não dão suporte a arquivos Parquet no estilo Hive, como Athena ou Redshift.

Quando ocorre a geração de metadados do Iceberg?

O Azure Databricks dispara a geração de metadados de forma assíncrona após a conclusão de uma transação de gravação do Delta Lake. Esse processo de geração de metadados usa a mesma computação que concluiu a transação Delta.

Observação

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, as tabelas Delta com confirmações frequentes podem agrupar várias confirmações Delta em uma única confirmação para metadados do Iceberg.

O Delta Lake garante que apenas um processo de geração de metadados esteja em andamento em um determinado recurso de computação. As confirmações que disparariam um segundo processo simultâneo de geração de metadados são confirmadas com êxito no Delta, mas não disparam 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 confirmações frequentes (segundos a minutos entre confirmações).

Veja Versões da tabela Delta e Iceberg.

Versões da tabela Delta e Iceberg

Tanto o Delta Lake quanto o Iceberg permitem consultas de viagem no tempo usando versões de tabela ou carimbos de data/hora armazenados em metadados de tabela.

Em geral, as versões das tabelas do Delta não se alinham com as versões das tabelas do Iceberg pela marca temporal de confirmação ou pela ID da versão. Para verificar a qual versão de uma tabela Delta corresponde uma determinada versão de uma tabela Iceberg, você pode usar as propriedades de tabela correspondentes. Consulte Verificar o status de geração de metadados do Iceberg.

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

Habilitar leituras do Iceberg em uma tabela adiciona os seguintes campos aos metadados de tabela do Unity Catalog e do Iceberg para acompanhar o status de 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 êxito.
converted_delta_timestamp O carimbo de data/hora da confirmação Delta mais recente para a qual os metadados do Iceberg foram gerados com êxito.

No Azure Databricks, você pode examinar esses campos de metadados realizando um dos seguintes procedimentos:

  • Revisão da seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
  • Revisando metadados de tabela com o Gerenciador de Catálogos.
  • Usar a API REST para obter uma tabela.

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

SHOW TBLPROPERTIES <table-name>;

Acionar 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. Essa operação é executada de forma síncrona, o que significa que, quando 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 foi iniciado.

Esta operação não deve ser necessária em condições normais, mas pode ajudar se você encontrar o seguinte:

  • Um cluster termina antes que a geração automática de metadados seja bem-sucedida.
  • Um erro ou falha de trabalho interrompe a geração de metadados.
  • Um cliente que não dá suporte à geração de metadados do UniForm Iceberg escreve na tabela Delta.

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte REPAIR TABLE.

Ler Iceberg usando um caminho JSON de metadados

Alguns clientes Iceberg exigem que você forneça um caminho para arquivos de metadados versionados para registrar tabelas externas do Iceberg. Sempre que o Azure Databricks 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 leitor do Iceberg para obter detalhes de configuração.

O Delta Lake armazena metadados de Iceberg no diretório de tabela usando o seguinte padrão:

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

No Azure Databricks, você pode examinar esse local de metadados realizando um dos seguintes procedimentos:

  • Revisão da seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
  • Revisando metadados de tabela com o Gerenciador de Catálogos.
  • Usando o seguinte comando com a API REST:
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

A resposta inclui as informações a seguir:

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

Importante

Os clientes de leitor do 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 do Parquet são removidos da tabela Delta com VACUUM.

Limitações

As seguintes limitações existem para todas as tabelas com leituras do Iceberg habilitadas:

  • As leituras de iceberg não funcionam em tabelas com vetores de exclusão habilitados. Confira O que são vetores de exclusão?
  • Tabelas delta com leituras de Iceberg habilitadas não dão suporte a tipos de VOID.
  • O suporte ao cliente do Iceberg é somente leitura. Não há suporte para gravações.
  • Os clientes leitores do Iceberg podem ter limitações individuais, independentemente do suporte do Azure Databricks para leituras do Iceberg. Consulte a documentação do cliente escolhido.
  • Os destinatários do Delta Sharing só podem ler a tabela como Delta, mesmo quando estão habilitadas as leituras do Iceberg.
  • Alguns recursos de tabela do Delta Lake usados pelas leituras do Iceberg não são compatíveis com alguns clientes leitores do Delta Sharing. Confira O que é o Compartilhamento Delta?.

O Feed de Dados de Alteração funciona para clientes Delta quando as leituras do Iceberg estão habilitadas, mas não é compatível com o Iceberg.