Use o UniForm para ler tabelas Delta com clientes Iceberg

O Delta Lake Universal Format (UniForm) permite que o senhor leia tabelas Delta com clientes de leitura Iceberg. Este recurso requer Databricks Runtime 14.3 LTS ou acima.

Importante

Para obter a documentação do recurso de tabela UniForm IcebergCompatV1 legado, 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 endpointdo catálogo Unity Catalog Iceberg.

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

Observação

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

Como o UniForm funciona?

O UniForm aproveita o fato de que o Delta Lake e o Iceberg consistem em arquivos de dados Parquet e uma camada de metadados. O UniForm gera automaticamente metadados Iceberg de forma assíncrona, sem reescrever os dados, para que os clientes Iceberg possam ler as tabelas Delta. Uma única cópia dos arquivos de dados atende a vários formatos.

Requisitos

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

A tabela Delta deve ser registrada no Unity Catalog. Ambas as tabelas gerenciais e externas são suportadas.
A tabela deve ter o mapeamento de colunas ativado. Consulte Renomear e soltar colunas com o mapeamento de colunas do Delta Lake.
A tabela Delta deve ter um minReaderVersion >= 2 e minWriterVersion >= 7. Consulte Como o Databricks gerencia a compatibilidade de recursos do Delta Lake?.
As gravações na tabela devem usar o Databricks Runtime 14.3 LTS ou acima.

Observação

O senhor não pode ativar vetores de exclusão em uma tabela com o UniForm Iceberg ativado.

Use REORG para desativar e limpar os vetores de exclusão enquanto ativa o UniForm Iceberg em uma tabela existente com vetores de exclusão ativados. Consulte Ativar ou fazer upgrade usando o REORG.

Ativar o UniForm Iceberg

Importante

A ativação do Delta UniForm define o recurso IcebergCompatV2 da tabela Delta, um recurso de protocolo de gravação. Somente os clientes que suportam esse recurso de tabela podem gravar em tabelas habilitadas para UniForm. O senhor deve usar o Databricks Runtime 14.3 LTS ou superior para gravar em tabelas Delta com esse recurso ativado.

O senhor pode desativar o UniForm desmarcando a propriedade delta.universalFormat.enabledFormats da tabela. As atualizações para as versões do protocolo do leitor e do gravador Delta Lake não podem ser desfeitas.

O senhor deve definir as seguintes propriedades da tabela para ativar 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. Esta tarefa deve ser concluída antes que os clientes externos possam query 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 estar ativado para usar o UniForm Iceberg. Isso acontece automaticamente se o senhor 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');

Habilitar alterando uma tabela existente

Em Databricks Runtime 15.4 LTS e acima, o senhor pode ativar ou atualizar UniForm Iceberg em uma tabela existente usando a seguinte sintaxe:

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

Ativar ou atualizar usando `REORG`

O senhor pode usar REORG para ativar o UniForm Iceberg e reescrever os 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 opções a seguir for verdadeira:

Sua tabela tem vetores de exclusão ativados.
O senhor ativou anteriormente a versão IcebergCompatV1 do UniForm Iceberg.
O senhor precisa ler de mecanismos do Iceberg que não suportam arquivos Parquet no estilo Hive, como o Athena ou o Redshift.

Quando o UniForm gera metadados do Iceberg?

O Databricks aciona 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 o mesmo compute que concluiu a transação Delta.

Observação

O senhor 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, as tabelas Delta com commit frequente podem agrupar vários Delta commit em um único commit para Iceberg metadados.

Delta Lake garante que apenas um processo de geração de metadados esteja em andamento a qualquer momento em um determinado recurso compute. que acionaria um segundo processo de geração de metadados concorrente com êxito commit para Delta, mas não acionaria a geração assíncrona de metadados Iceberg. Isso evita a latência em cascata para a geração de metadados para cargas de trabalho com confirmação frequente (segundos a minutos entre confirmações).

Consulte as versões das mesas Delta e Iceberg.

Versões de mesa Delta e Iceberg

Delta Lake e Iceberg permitem consultas de viagem do tempo usando versões de tabela ou registros de data e hora armazenados nos metadados da tabela.

Em geral, as versões da tabela Delta não se alinham às versões do Iceberg pelo registro de data e hora do commit 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, o senhor pode usar as propriedades da tabela correspondente. Consulte Verificar o status de geração de metadados do Iceberg.

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

O UniForm adiciona os seguintes campos aos metadados da tabela Unity Catalog e 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 para a qual os metadados do Iceberg foram gerados com sucesso.
`converted_delta_timestamp`	O carimbo de data/hora do último commit Delta para o qual os metadados do Iceberg foram gerados com sucesso.

No Databricks, o senhor pode revisar esses campos de metadados seguindo um dos seguintes procedimentos:

Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
Revisão dos metadados da tabela com o Catalog Explorer.
Usando a API REST para obter uma tabela.

Consulte a documentação do cliente do leitor Iceberg para saber como revisar as propriedades da tabela fora do Databricks. Para OSS Apache Spark, você pode ver essas propriedades usando a seguinte sintaxe:

SHOW TBLPROPERTIES <table-name>;

Acione 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. Esta execução é executada de forma síncrona, ou seja, quando ela 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 começar.

Essas operações não devem ser necessárias em condições normais, mas podem ajudar se você encontrar o seguinte:

Um clusters termina antes que a geração automática de metadados seja bem-sucedida.
Um erro ou falha Job 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 seguinte sintaxe para acionar manualmente a geração de metadados do Iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte TABELA DE REPAROS.

Ler usando um caminho JSON de metadados

Alguns clientes do Iceberg exigem que o senhor 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 para o 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 do leitor Iceberg para obter detalhes de configuração.

O Delta Lake armazena os metadados do Iceberg no diretório da tabela, usando o seguinte padrão:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

No Databricks, o senhor pode revisar esse local de metadados executando uma das seguintes ações:

Revisando a seção Delta Uniform Iceberg retornada por DESCRIBE EXTENDED table_name.
Revisão dos metadados da 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 a seguinte informação:

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

Importante

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

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

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

Os clientes conhecidos por oferecer suporte à API do catálogo REST do Iceberg incluem o Apache Spark, o Apache Flink, o Trino e o Snowflake. Além de configurar a autenticação e a autorização, o senhor deve configurar o acesso do cliente ao local de armazenamento cloud que contém os arquivos e metadados da tabela Delta com UniForm ativado. Consulte a documentação do cliente leitor Iceberg para obter detalhes sobre a configuração.

Autenticação e autorização

Há dois requisitos para acessar os dados registrados em Unity Catalog usando o api/2.1/unity-catalog/iceberg endpoint de um serviço externo:

Autentique-se usando OAuth ou um Databricks pessoal access token. Consulte Autenticar o acesso a Databricks recurso.
Ative o acesso externo a dados para sua 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 Unity Catalog.

Exemplo de configuração do Apache Spark

A seguir, um exemplo das configurações para que o Apache Spark leia o UniForm como Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing Uniform tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential": "<client-id>:<secret>",
"spark.sql.catalog.<spark-catalog-name>.scope": "all-apis,sql",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"

Substitua as seguintes variáveis:

<uc-catalog-name>: Nome do catálogo no Unity Catalog que contém suas tabelas Uniformes.
<workspace-url>: URL do site Databricks workspace.
<client-id>: O ID do cliente da entidade de serviço.
<secret>: O segredo da entidade de serviço.

Observação

Como alternativa, o senhor pode configurar o acesso usando tokens PAT (obsoleto) usando "spark.sql.catalog.<spark-catalog-name>.token":"<token>". Remova as configurações de oauth-server-uri, credential e scope ao usar tokens PAT.

Com essas configurações, o senhor pode consultar tabelas Uniformes como Iceberg no Apache Spark usando o identificador <catalog-name>.<schema-name>.<table-name>. Para acessar tabelas em vários catálogos, você deve configurar cada catálogo separadamente.

Quando o senhor consultar tabelas no Unity Catalog usando configurações do Spark, tenha em mente o seguinte:

Os identificadores de objetos 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ê precisará do "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" somente se estiver executando procedimentos armazenados específicos do Iceberg.
Se estiver usando um provedor cloud para armazenamento, o senhor deverá adicionar os jars do pacote cloud-specific Iceberg como spark pacote:
- 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 configuração do Snowflake

A seguir, um exemplo das definições de configuração recomendadas para permitir que o Snowflake se integre ao Unity Catalog Iceberg REST para ler o UniForm como Iceberg usando o OAuth:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg',
    WAREHOUSE = '<catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = '<workspace-url>/oidc/v1/token'
    OAUTH_CLIENT_ID = '<client-id>'
    OAUTH_CLIENT_SECRET = '<secret>'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;

Substitua as seguintes variáveis:

<catalog-name>: Nome do catálogo no Unity Catalog que contém suas tabelas UniForm.
<workspace-url>: URL do site Databricks workspace.
<client-id>: O ID do cliente da entidade de serviço.
<secret>: O segredo da entidade de serviço.

Exemplo de curl da API REST

O senhor 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>

Em seguida, você deve receber uma resposta como esta:

{
  "metadata-location": "gs://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "gcs.oauth2.token": "<temporary-oauth-token>",
    "gcs.oauth2.token-expires-at": "<epoch-ts-in-millis>"
  }
}

Observação

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

Limitações

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

O UniForm não funciona em tabelas com vetores de exclusão ativados. Consulte O que são vetores de exclusão?.
Delta As tabelas com o UniForm ativado não são compatíveis com os tipos VOID.
Os clientes Iceberg só podem ler do UniForm. Gravações não são suportadas.
Os clientes do leitor Iceberg podem ter limitações individuais, independentemente do UniForm. Consulte a documentação do cliente escolhido.
Os destinatários do Delta Sharing só podem ler a tabela como Delta, mesmo quando o UniForm está ativado.
Alguns recursos da tabela Delta Lake usados por UniForm Iceberg não são suportados por alguns clientes leitores Delta Sharing. Consulte O que é Delta Sharing?

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

Use o UniForm para ler tabelas Delta com clientes Iceberg

Como o UniForm funciona?

Requisitos

Ativar o UniForm Iceberg

Ativar durante a criação da tabela

Habilitar alterando uma tabela existente

Ativar ou atualizar usando REORG

Quando o UniForm gera metadados do Iceberg?

Versões de mesa Delta e Iceberg

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

Acione manualmente a conversão de metadados do Iceberg

Ler usando um caminho JSON de metadados

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

Autenticação e autorização

Exemplo de configuração do Apache Spark

Exemplo de configuração do Snowflake

Exemplo de curl da API REST

Limitações

Ativar ou atualizar usando `REORG`