Pular para o conteúdo principal
Última atualização em

Ler tabelas Delta Lake com clientes Iceberg

Disponível no Databricks Runtime 14.3 LTS e acima, as leituras do Iceberg configuram tabelas do Delta Lake para gerar automaticamente metadados do Iceberg, para que os clientes do Iceberg possam ler dados do Delta Lake sem reescrever arquivos.

Você pode configurar uma conexão externa para que o Unity Catalog atue como um catálogo Iceberg. Consulte Acessar tabelas do Databricks a partir de clientes Apache Iceberg.

Como funcionam as leituras Iceberg​

Tanto o Delta Lake quanto o Apache Iceberg consistem em arquivos de dados Parquet e uma camada de metadados. Quando você ativa as leituras Iceberg, o Databricks configura suas tabelas para usar o Universal Format (UniForm) para a camada de metadados. O UniForm gera automaticamente metadados Iceberg de forma assíncrona junto com os metadados do Delta Lake, sem reescrever os arquivos de dados Parquet. Uma única cópia dos arquivos de dados oferece suporte a clientes Delta e Iceberg.

Ao usar leituras do Iceberg, considere o seguinte:

  • As tabelas Delta Lake com leituras Iceberg ativadas usam Zstandard em vez de Snappy como o codec de compressão para os arquivos de dados Parquet subjacentes.
  • A geração de metadados do Iceberg é executada de forma assíncrona no compute usado para gravar dados em tabelas do Delta Lake, o que pode aumentar o uso de recurso do driver.

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

Requisitos​

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

nota

Não é possível ativar vetores de exclusão em uma tabela com leituras de Iceberg ativadas.

Use REORG para desativar e limpar vetores de exclusão enquanto habilita leituras do Iceberg em uma tabela existente com vetores de exclusão ativados. Consulte Habilitar ou atualizar o suporte de leitura do Iceberg usando REORG.

Habilitar leituras de Iceberg​

nota

A ativação de leituras Iceberg adiciona o recurso de protocolo de gravação IcebergCompatV2 e atualiza o protocolo de gravação. Somente clientes que suportam esse recurso de tabela podem gravar na tabela. Isso pode afetar a compatibilidade com clientes externos do Delta Lake. Consulte Compatibilidade de recursos e protocolos do Delta Lake.

Ao habilitar as leituras de Iceberg pela primeira vez, a geração assíncrona de metadados é iniciada. Esta tarefa deve ser concluída antes que clientes externos possam query a tabela usando Iceberg. Consulte Verificar o status da geração de metadados do Iceberg.

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

Durante a criação da tabela​

O mapeamento de coluna é ativado automaticamente quando você habilita leituras Iceberg durante a criação da tabela:

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

A Databricks recomenda que você defina delta.columnMapping.mode = id para fins de compatibilidade. Consulte Renomear e eliminar colunas com o mapeamento de colunas do Delta Lake.

Em uma tabela existente​

Para ativar leituras Iceberg em uma tabela existente no Databricks Runtime 15.4 LTS e acima:

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

Para obter detalhes sobre o modo de mapeamento de coluna name, consulte Modos de mapeamento de coluna.

Habilite ou atualize o suporte de leitura do Iceberg usando REORG​

Use REORG para habilitar leituras de Iceberg se qualquer uma das seguintes condições for verdadeira:

  • Você ativou vetores de exclusão em sua tabela.
  • Você ativou anteriormente a versão IcebergCompatV1 do UniForm Iceberg.
  • Você precisa ler a partir de engines Iceberg que não oferecem suporte a arquivos Parquet no estilo Hive, como o Athena ou o Redshift.

Para habilitar leituras de Iceberg e reescrever arquivos de dados subjacentes, use REORG como no exemplo a seguir:

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

Verifique se as leituras do Iceberg estão ativadas​

Use DESCRIBE EXTENDED para verificar se as leituras de Iceberg estão habilitadas para sua tabela:

SQL
DESCRIBE EXTENDED catalog_name.schema_name.table_name;

Procure a seção Delta Uniform Iceberg na saída. Se esta seção estiver presente, as leituras Iceberg estarão habilitadas em sua tabela.

Como alternativa, você pode usar SHOW TBLPROPERTIES:

SQL
SHOW TBLPROPERTIES catalog_name.schema_name.table_name;

Verifique as seguintes propriedades:

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

Se ambas as propriedades estiverem presentes com esses valores, as leituras do Iceberg estarão ativadas.

Desativar leituras do Iceberg​

Você pode desativar as leituras do Iceberg cancelando a definição da propriedade de tabela delta.universalFormat.enabledFormats:

SQL
ALTER TABLE table_name UNSET TBLPROPERTIES ('delta.universalFormat.enabledFormats');

As atualizações para as versões do protocolo de leitura e gravação do Delta Lake não podem ser desfeitas. Consulte Compatibilidade de recursos e protocolos do Delta Lake.

Geração de metadados Iceberg​

O Databricks Trigger a geração de metadados de forma assíncrona após a conclusão de uma transação de gravação do Delta Lake. Este processo de geração de metadados usa o mesmo compute que concluiu a transação do Delta Lake.

Você também pode Trigger manualmente a geração de metadados Iceberg. Veja Trigger manualmente a conversão de metadados Iceberg.

Para evitar latências de gravação associadas à geração de metadados, tabelas do Delta Lake com commits frequentes podem agrupar vários commits do Delta Lake em um único commit para metadados do Iceberg.

O Delta Lake garante que apenas um processo de geração de metadados esteja em andamento em um determinado recurso compute. commit que Trigger um segundo processo de geração de metadados concorrente é confirmado com êxito no Delta Lake, mas não Trigger a geração assíncrona de metadados Iceberg. Isso evita latência em cascata para a geração de metadados em cargas de trabalho com commit frequentes (segundos a minutos entre commit).

Consulte Versões de tabelas Delta e Iceberg.

Versões de tabela Delta e Iceberg​

O Delta Lake e o Iceberg permitem queries de viagem do tempo usando versões de tabela ou Timestamp armazenados nos metadados da tabela.

Não há garantia de que as versões da tabela Delta Lake estejam alinhadas com as versões do Iceberg pelo Timestamp do commit ou pelo ID da versão. Para verificar a qual versão de uma tabela Delta Lake uma determinada versão de uma tabela Iceberg corresponde, use as propriedades de tabela correspondentes. Consulte Verificar o status da geração de metadados do Iceberg.

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

A ativação de leituras Iceberg em uma tabela adiciona os seguintes campos aos metadados da tabela do Unity Catalog e do 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 Lake para a qual os metadados Iceberg foram gerados com sucesso.

converted_delta_timestamp

O Timestamp do commit mais recente do Delta Lake para o qual os metadados Iceberg foram gerados com sucesso.

Campo de metadados

Descrição

converted_delta_version

A versão mais recente da tabela Delta Lake para a qual os metadados Iceberg foram gerados com sucesso.

converted_delta_timestamp

O Timestamp do commit mais recente do Delta Lake para o qual os metadados Iceberg foram gerados com sucesso.

No Databricks, você pode revisar esses campos de metadados fazendo uma das seguintes ações:

  • Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
  • Revisando metadados de tabela com o Catalog Explorer.

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

SQL
SHOW TBLPROPERTIES <table-name>;

Trigger manualmente a conversão de metadados do Iceberg​

Você pode Trigger manualmente a geração de metadados Iceberg para a versão mais recente da tabela Delta Lake. Esta operação possui execução síncrona. Quando concluído, o conteúdo da tabela disponível no Iceberg reflete a versão mais recente da tabela Delta Lake disponível quando o processo de conversão começou.

Esta operação não é necessária em condições normais. Use-o para recuperar do seguinte:

  • Um cluster é encerrado antes que a geração automática de metadados seja concluída com êxito.
  • Um erro ou falha no job interrompe a geração de metadados.
  • Um cliente que não oferece suporte à geração de metadados do UniForm Iceberg grava na tabela Delta Lake.

Use a sintaxe a seguir para Trigger a geração de metadados do Iceberg manualmente:

SQL
MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte REPAIR TABLE.

Ler Iceberg usando um caminho JSON de metadados​

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

Para detalhes de configuração, consulte a documentação do seu cliente de leitura Iceberg específico.

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

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

No Databricks, você pode revisar este local de metadados fazendo uma das seguintes ações:

  • Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
  • Revisando metadados de tabela com o Catalog Explorer.
importante

Clientes leitores de Iceberg baseados em caminho podem exigir a atualização e a atualização manual dos caminhos JSON de metadados para ler as versões atuais da tabela. Você pode encontrar erros ao consultar tabelas Iceberg usando versões desatualizadas, pois os arquivos de dados Parquet são removidos da tabela Delta Lake com VACUUM. Consulte VACUUM e limpeza de metadados do Iceberg.

Limpeza de metadados do VACUUM e Iceberg​

Em tabelas Delta Lake com leituras Iceberg ativadas, os metadados do Iceberg se acumulam no diretório metadata/ à medida que a tabela é alterada. As operações OPTIMIZE e de conversão para Iceberg não excluem os metadados de versões de tabela mais antigas. Somente VACUUM a remove.

Disponível no Databricks Runtime 17.2 e acima, VACUUM exclui arquivos não rastreados no diretório metadata/ enquanto mantém os metadados do Iceberg que os clientes precisam para ler as versões atuais da tabela. Esta limpeza é executada no modo FULL, que é o default para VACUUM.

Para limpar metadados de versões de tabela mais antigas, faça a execução de VACUUM após o período de retenção delta.deletedFileRetentionDuration ter decorrido:

SQL
VACUUM table_name FULL

Consulte Modo completo versus modo lite para saber mais sobre os modos de vacuum e Configurar a retenção de dados para consultas de viagem do tempo para saber mais sobre o período de retenção.

Se a otimização preditiva estiver habilitada, o Databricks gerencia automaticamente essa limpeza, portanto, não é necessária a execução manual de VACUUM para a limpeza de metadados do Iceberg.

Limitações​

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

  • O suporte ao cliente Iceberg é somente leitura. Gravações não são suportadas.

    • Os clientes de leitura Iceberg podem ter limitações individuais, independentemente do suporte do Databricks para leituras Iceberg. Consulte a documentação do cliente escolhido.

  • Os vetores de deleção não são compatíveis com leituras do Iceberg v2. No entanto, o Apache Iceberg v3 é compatível com vetores de deleção. Consulte Usar recursos do Apache Iceberg v3 e Vetores de deleção no Databricks.

  • As leituras do Iceberg não podem ser habilitadas em views materializadas ou tabelas de transmissão usando IcebergCompatV2. Para views materializadas e tabelas de transmissão gerenciadas por pipeline, você pode habilitar o acesso externo ao Iceberg usando IcebergCompatV3. Consulte Habilitar acesso a dados externos para tabelas de transmissão e views materializadas.

  • A tabela Delta Lake deve ser acessada por nome (não por caminho) para Trigger automaticamente a geração de metadados do Iceberg.

  • As tabelas do Delta Lake com leituras Iceberg ativadas não oferecem suporte a tipos VOID.

  • Alguns recursos de tabela do Delta Lake usados por leituras do Iceberg não são compatíveis com alguns clientes de leitura do OpenSharing. Consulte O que é o OpenSharing?.

  • Os destinatários do OpenSharing podem ler tabelas Delta Lake com leituras Iceberg ativadas como tabelas Iceberg usando a API do Catálogo REST do Iceberg. Esse recurso está em Prévia Pública. Consulte Ativar o compartilhamento para clientes Iceberg externos.

  • O feed de dados de alteração legado funciona para clientes Delta quando as leituras do Iceberg estão ativadas, mas não tem suporte no Iceberg. Consulte Feed de dados de alteração legado para Delta Lake.

Nesta página