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. [[ ## completed ##]]

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. [[ ## completed ##]] 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. [[ ## completed ##]] 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. [[ ## completed ##]] 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. [[ ## completed ##]]

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 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. 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 Lake com VACUUM.

Limpeza de metadados do VACUUM e Iceberg​

A partir do Databricks Runtime 17.2, o comando VACUUM exclui arquivos não rastreados no diretório UniForm metadata/ enquanto preserva os metadados Iceberg que ainda estão acessíveis.

A conversão do UniForm realiza a expiração do Snapshot do Iceberg internamente, mas usa cleanExpiredFiles(false) por default. Como resultado, OPTIMIZE e a conversão regular do UniForm apenas tornam os metadados antigos do Iceberg inacessíveis, mas não os excluem fisicamente.

Para remover fisicamente metadados do Iceberg inacessíveis, faça a execução de FULL VACUUM após o período de retenção delta.deletedFileRetentionDuration ter decorrido. [[ ## completed ##]] Consulte Configurar a retenção de dados para query de viagem do tempo.

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

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 em vez disso. [[ ## completed ##]] Esse recurso está em Prévia Pública. 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