Partilhar via

Legado UniForm IcebergCompatV1

  • Artigo

Importante

Esta documentação foi desativada e pode não ser atualizada. Os produtos, serviços ou tecnologias mencionados neste conteúdo não são mais suportados. Consulte Usar UniForm para ler tabelas Delta com clientes Iceberg.

Importante

Esse recurso está na visualização pública no Databricks Runtime 13.2 e superior.

O Formato Universal Delta (UniForm) permite que você leia tabelas Delta com clientes leitores 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 Unity Catalog atue como um catálogo Iceberg. Consulte Ler usando o ponto de extremidade do catálogo Unity Catalog Iceberg.

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.

Requisitos

Para habilitar o UniForm, você deve cumprir os seguintes requisitos:

Ativar Delta UniForm

Importante

A habilitação do Delta UniForm define o recurso IcebergCompatV1de 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 13.2 ou superior para gravar em tabelas Delta com esse recurso habilitado.

Você pode desativar o UniForm desdefinindo a delta.universalFormat.enabledFormats propriedade table. Não é possível desativar o mapeamento de colunas depois que ele for habilitado, e as atualizações para as versões do protocolo de leitor e gravador Delta Lake não podem ser desfeitas.

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

'delta.universalFormat.enabledFormats' = 'iceberg'

Você também deve habilitar o mapeamento de colunas e IcebergCompatV1 usar o UniForm. Eles sã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 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.

Nota

Se você planeja usar o BigQuery como seu cliente leitor Iceberg, deverá definir spark.databricks.delta.write.dataFilesToSubdir como true no Azure Databricks para acomodar um requisito do BigQuery para layout de dados.

Consulte Limitações.

Quando o UniForm gera metadados do Iceberg?

O Azure Databricks aciona a geração de metadados do Iceberg de forma assíncrona após a conclusão de uma transação de gravação Delta Lake 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 do Iceberg.

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

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 usando o Gerenciador de Catálogos. 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 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

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 dos metadados do Iceberg.

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

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. Você deve configurar o acesso ao armazenamento de objetos na nuvem subjacente que contém a tabela Delta com UniForm habilitado. Consulte a documentação do cliente leitor 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 aos 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 por <api-root>.

Nota

Ao consultar tabelas no Unity Catalog usando esse método, os identificadores de objeto usam o seguinte padrão:

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

Esse padrão usa o mesmo namepacing de três camadas presente no Unity Catalog, mas adiciona um prefixo unityadicional.

Versões de tabelas 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 são alinhadas 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 da tabela correspondente definidas na tabela Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

Limitações

As seguintes limitações existem:

  • 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 LIST, MAPe 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 clientes do leitor Iceberg versão 1.2.0 e inferior não suportam INT96 o 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 Unity Catalog Iceberg não se destina a cargas de trabalho de produção em grande escala. Você pode experimentar limitação de taxa se exceder um limite de 5 consultas por segundo.

Os seguintes recursos 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