Partilhar via

Use o UniForm para ler tabelas Delta com clientes Iceberg

  • Artigo

O formato universal Delta Lake (UniForm) permite que você leia tabelas Delta com clientes leitores Iceberg. Esse recurso requer o Databricks Runtime 14.3 LTS ou superior.

Importante

Para obter documentação para o recurso de tabela UniForm IcebergCompatV1 herdado, consulte Legacy UniForm IcebergCompatV1.

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

UniForm Iceberg usa Zstandard em vez de Snappy como o codec de compressão para arquivos de dados Parquet subjacentes.

Nota

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

Como funciona o UniForm?

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 do Iceberg de forma assíncrona, sem reescrever dados, para que os clientes do Iceberg possam ler tabelas Delta. Uma única cópia dos arquivos de dados serve vários formatos.

Requisitos

Para habilitar o UniForm Iceberg, os seguintes requisitos devem ser atendidos:

Nota

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

Use REORG para desabilitar e limpar vetores de exclusão enquanto habilita o UniForm Iceberg em uma tabela existente com vetores de exclusão habilitados. Consulte Habilitar ou atualizar usando REORG.

Ativar UniForm Iceberg

Importante

A habilitação do Delta UniForm define o recurso IcebergCompatV2de tabela Delta , um recurso de protocolo de gravação. Somente os clientes que oferecem suporte a esse recurso de tabela podem gravar em tabelas habilitadas para UniForm. Você deve usar o Databricks Runtime 14.3 LTS ou superior para gravar em tabelas Delta com esse recurso habilitado.

Você pode desativar o UniForm desdefinindo a delta.universalFormat.enabledFormats propriedade table. As atualizações para as versões do protocolo de leitor e gravador Delta Lake não podem ser desfeitas.

Você deve definir as seguintes propriedades de tabela para habilitar o UniForm Iceberg:

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

Quando você habilita o UniForm pela primeira vez, a geração assíncrona de metadados começa. Esta 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.

Ativar durante a criação da tabela

O mapeamento de colunas deve ser habilitado para usar o UniForm Iceberg. Isso acontece automaticamente se você ativar o UniForm Iceberg durante a criação da tabela, como no exemplo a seguir:

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

Ativar alterando uma tabela existente

No Databricks Runtime 15.4 LTS e superior, você pode habilitar ou atualizar o UniForm Iceberg em uma tabela existente usando a seguinte sintaxe:

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

Habilitar ou atualizar usando REORG

Você pode usar REORG para habilitar o UniForm 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 ativados.
  • Você ativou anteriormente a IcebergCompatV1 versão do UniForm Iceberg.
  • Você precisa ler a partir de motores Iceberg que não suportam arquivos Parquet estilo Hive, como Athena ou Redshift.

Quando o UniForm gera 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 Delta Lake. Esse processo de geração de metadados usa o mesmo cálculo que concluiu a transação Delta.

Nota

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

O Delta Lake garante que apenas um processo de geração de metadados esteja em andamento a qualquer momento em um determinado recurso de computação. Confirmações que acionariam um segundo processo simultâneo de geração de metadados com êxito no Delta, mas não acionariam a geração assíncrona de metadados do Iceberg. Isso evita a latência em cascata para a geração de metadados para cargas de trabalho com confirmações frequentes (segundos a minutos entre confirmações).

Veja as versões das tabelas Delta e Iceberg.

Versões de tabelas Delta e Iceberg

Delta Lake e 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 da tabela Delta não se alinham às versões do Iceberg pelo carimbo de data/hora de confirmação ou pelo 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 da tabela correspondente. Consulte Verificar o status de geração de metadados do Iceberg.

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

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

Campo de metadados Description
converted_delta_version A última versão da tabela Delta para a qual os metadados do Iceberg foram gerados com sucesso.
converted_delta_timestamp O carimbo de data/hora da última confirmação Delta para a qual os metadados do Iceberg foram gerados com sucesso.

No Azure Databricks, você pode revisar esses campos de metadados seguindo um destes procedimentos:

  • Revisão da seção retornada Delta Uniform Iceberg por DESCRIBE EXTENDED table_name.
  • Revisão de metadados de tabela com o Catalog Explorer.
  • Usando 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 concluída, o conteúdo da tabela disponível no Iceberg reflete 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 suporta a gneration de metadados UniForm Iceberg grava na tabela Delta.

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte TABELA DE REPARAÇÃO.

Ler usando um caminho JSON de metadados

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

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 Azure Databricks, você pode revisar esse local de metadados seguindo um destes procedimentos:

  • Revisão da seção retornada Delta Uniform Iceberg por DESCRIBE EXTENDED table_name.
  • Revisão de metadados de 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 as seguintes informações:

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

Importante

Os clientes de leitor 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 do Iceberg usando versões desatualizadas, pois os arquivos de dados do Parquet são removidos da tabela Delta com VACUUM.

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

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

Os clientes conhecidos por suportar a API do catálogo Iceberg incluem Apache Spark, Flink e Trino. Consulte a documentação do cliente leitor Iceberg para obter detalhes de configuração.

Autenticação e autorização

Há dois requisitos para acessar dados registrados no Unity Catalog usando o api/2.1/unity-catalog/iceberg ponto de extremidade de serviços externos:

Exemplo de configuração do Apache Spark

A seguir está um exemplo das configurações usadas para configurar o OSS Apache Spark para ler 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.type": "rest",
"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.warehouse": "<uc_catalog_name>"

Substitua a URL completa do espaço de trabalho no qual você gerou o token de acesso pessoal por <api-root>.

Ao consultar tabelas no Unity Catalog usando configurações do Spark, lembre-se do seguinte:

  • Os identificadores de objeto usam o padrão unity.<schema-name>.<table-name>.

    Esse padrão usa o mesmo namespace de três camadas usado no Unity Catalog, mas com o nome do catálogo substituído por unity.

  • Você só precisa "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" se estiver executando procedimentos armazenados específicos do Iceberg.

  • Se você estiver usando um provedor de nuvem para armazenamento, deverá adicionar os frascos do pacote Iceberg específicos da nuvem como pacotes spark:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Para obter detalhes, consulte a documentação da integração do Iceberg AWS para o Spark.

Exemplo de curl da API REST

Você também pode usar uma chamada de API REST como a deste exemplo curl para carregar uma tabela:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Você deve então receber uma resposta como esta:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Nota

O expires-at-ms campo na resposta indica o tempo de expiração das credenciais e tem um tempo de expiração padrão de uma hora. Para um melhor desempenho, faça com que o cliente armazene as credenciais em cache até o tempo de expiração antes de solicitar uma nova.

Limitações

Existem as seguintes limitações para todas as tabelas UniForm:

  • O UniForm não funciona em tabelas com vetores de exclusão habilitados. Consulte O que são vetores de exclusão?.
  • As tabelas delta com UniForm ativado não suportam VOID tipos.
  • Os clientes do Iceberg só podem ler a partir do UniForm. Não há suporte para gravações.
  • Os clientes do leitor Iceberg podem ter limitações individuais, independentemente do UniForm. Consulte a documentação do cliente escolhido.
  • Os destinatários do Compartilhamento Delta só podem ler a tabela como Delta, mesmo quando o UniForm está habilitado.
  • Alguns recursos de tabela Delta Lake usados pelo UniForm Iceberg não são suportados por alguns clientes de leitor Delta Sharing. Consulte O que é Delta Sharing?.

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