Usar o UniForm para fazer a leitura de tabelas Delta com clientes Iceberg

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

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

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

Como funciona o UniForm?

O UniForm aproveita o fato de que tanto o Delta Lake quanto o 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 a vários formatos.

Requisitos

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

• A tabela Delta deve ser registrada no Catálogo Unity. Há suporte para tabelas gerenciadas e externas.
• A tabela deve ter o mapeamento de colunas habilitado. Confira Renomear e remover colunas usando o mapeamento de colunas do Delta Lake.
• A tabela Delta deve ter um minReaderVersion>= 2 e minWriterVersion>= 7. Confira Como o Azure Databricks gerencia a compatibilidade de recursos do Delta Lake?
• As gravações na tabela devem usar o Databricks Runtime 14.3 LTS ou superior.

Habilitar o UniForm Iceberg

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 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 durante a criação da tabela

O Mapeamento de coluna deve estar habilitado para usar o UniForm Iceberg. Isso ocorrerá automaticamente se você habilitar 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');

Habilitar alterando uma tabela existente

No Databricks Runtime 15.4 LTS e versões posteriores, 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 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 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 do Delta Lake. Esse processo de geração de metadados usa a mesma computação que concluiu a transação Delta.

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 a qualquer momento em um determinado recurso de computação. As confirmações que acionariam um segundo processo simultâneo de geração de metadados são confirmadas com êxito com o Delta, mas não acionam 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 da tabela Delta não se alinham às versões do Iceberg pelo carimbo de data/hora de confirmação nem 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

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

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 oferece suporte à geração de metadados UniForm Iceberg grava na tabela Delta.

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

Confira REPARAR TABELA.

Leitura 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. 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 do 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 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"
    }
}

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

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

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

Autenticação e autorização

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

• Autenticar usando OAuth ou um token de acesso pessoal do Azure Databricks. Consulte Autenticar o acesso a recursos do Azure Databricks.
• Habilitar Acesso a dados externos para o metastore. Isso limita o acesso a usuários que têm o privilégio EXTERNAL USE SCHEMA no esquema do qual a API está lendo. Consulte Controlar o acesso externo aos dados no Catálogo do Unity.

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 para <api-root>.

Ao consultar tabelas de consulta no Catálogo do Unity usando configurações do Spark, tenha o seguinte em mente:

• 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 Catálogo do Unity, mas com o nome do catálogo substituído por unity.

• Você só precisa de "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 jars do pacote Iceberg específicos da nuvem como pacotes do 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 do API REST

Você também pode usar uma chamada à API REST como a deste exemplo de 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 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>"
  }
}

Limitações

As seguintes limitações existem para todas as tabelas UniForm:

• UniForm não funciona em tabelas com vetores de exclusão habilitados. Confira O que são vetores de exclusão?
• Tabelas Delta com UniForm habilitado não dão suporte a tipos VOID.
• Os clientes da Iceberg só podem ler a partir do UniForm. Não há suporte para gravações.
• Os clientes leitores do 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 do Delta Lake usados pelo UniForm Iceberg não são compatíveis com alguns clientes de leitor do Compartilhamento Delta. Confira O que é o Compartilhamento Delta?.

O feed de dados de alterações funciona para clientes Delta quando o UniForm está habilitado, mas não tem suporte no Iceberg.