UniForm IcebergCompatV1 Herdado

O Delta Universal Format (UniForm) permite que você leia tabelas Delta com clientes leitores do Iceberg.

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 como se fossem tabelas Iceberg. Uma única cópia dos arquivos de dados serve ambos os formatos.

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.

Requisitos

Para habilitar o UniForm, você deve atender aos seguintes requisitos:

• 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 13.2 ou superior.

Habilitar o Delta UniForm

A propriedade de tabela a seguir habilita o suporte UniForm para Iceberg. iceberg é o único valor válido.

'delta.universalFormat.enabledFormats' = 'iceberg'

Você também deve habilitar o mapeamento de coluna e IcebergCompatV1 usar o UniForm. Eles serão definidos automaticamente se você habilitar o UniForm durante a criação da tabela, como no exemplo a seguir:

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

Se você criar uma nova tabela com uma instrução CTAS, deverá especificar manualmente o mapeamento de coluna, como no exemplo a seguir:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

Se você estiver alterando uma tabela existente, deverá especificar todas essas propriedades, como no exemplo a seguir:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = '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.

Confira Limitações.

Quando o UniForm gera metadados do Iceberg?

O Azure Databricks aciona a geração de metadados do Iceberg de forma assíncrona depois que uma transação de gravação do Delta Lake é concluída usando a mesma computação que concluiu a transação Delta. 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 do Iceberg, as tabelas Delta com confirmações frequentes podem agrupar várias confirmações Delta em uma única confirmação Iceberg.

O Delta Lake garante que apenas um processo de geração de metadados do Iceberg esteja em andamento a qualquer momento. As confirmações que acionariam um segundo processo simultâneo de geração de metadados do Iceberg serão comprometidas com êxito com o Delta, mas não acionarão 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.

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 revisar esses campos de metadados usando o Catalog Explorer. Esses campos e valores também são retornados ao 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

Você pode encontrar o caminho desse arquivo usando o Catalog Explorer. Para tabelas com UniForm habilitado, os detalhes da tabela Delta incluem um campo para o local de metadados do Iceberg.

Você também pode usar a API REST para obter todos os detalhes de uma tabela, incluindo o local dos metadados. Use o seguinte comando :

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. Você deve configurar o acesso ao armazenamento de objetos de nuvem subjacente que contém a tabela Delta com UniForm habilitado. Consulte a documentação do cliente leitor do Iceberg para obter detalhes de configuração.

Você deve gerar e configurar um token de acesso pessoal do Azure Databricks para permitir que outros serviços se conectem ao Catálogo Unity. Consulte Autenticar o acesso a recursos do Azure Databricks.

A seguir está um exemplo das configurações 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.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"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.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

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

unity.<catalog-name>.<schema-name>.<table-name>

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 Iceberg e Delta não se alinham pelo carimbo de data/hora de confirmação ou pelo ID da versão. Se desejar 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 definidas na tabela Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

Limitações

As seguintes limitações existem:

• UniForm não funciona em tabelas com vetores de exclusão habilitados. Confira O que são vetores de exclusão?
• As tabelas delta com UniForm habilitado não oferecem suporte aos tipos LIST, MAP e 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 clientes leitores Iceberg versão 1.2.0 e inferior não suportam INT96 tipo de carimbo de data/hora escrito pelo Apache Spark. Use o seguinte código em blocos de anotações que gravam em tabelas UniForm para evitar essa limitação: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
• A versão de visualização pública do ponto de extremidade Iceberg do Catálogo Unity não se destina a cargas de trabalho de produção em larga escala. Você pode enfrentar limitação de taxa se exceder um limite de 5 consultas por segundo.

Os seguintes recursos do Delta Lake funcionam para clientes Delta quando o UniForm está habilitado, mas não têm suporte no Iceberg:

• Alterar feed de dados
• Compartilhamento Delta