Pular para o conteúdo principal

Legado UniForm IcebergCompatV1

important

Essa documentação foi descontinuada e pode não estar atualizada. O produto, o serviço ou a tecnologia mencionados neste conteúdo não são mais suportados. Veja as tabelas Ler Delta com clientes Iceberg.

info

Visualização

Esse recurso está em Public Preview em Databricks Runtime 13.2 e acima.

O Delta Universal Format (UniForm) permite que o senhor leia tabelas Delta com clientes de leitura 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 Iceberg de forma assíncrona, sem reescrever dados, para que os clientes Iceberg possam ler tabelas Delta como se fossem tabelas Iceberg. Uma única cópia dos arquivos de dados atende aos dois formatos.

O senhor pode configurar uma conexão externa para que o Unity Catalog atue como um catálogo Iceberg. Consulte Ler usando o catálogo Unity Catalog Iceberg endpoint .

nota

UniForm A geração de metadados é executada de forma assíncrona no site compute usado para gravar dados nas tabelas Delta, o que pode aumentar o uso do recurso do driver.

Requisitos​

Para ativar o UniForm, o senhor deve atender aos seguintes requisitos:

Ativar o Delta UniForm​

important

Ativar Delta UniForm define o recurso de tabela Delta IcebergCompatV1, um recurso de protocolo de gravação. Somente clientes que suportam esse recurso de tabela podem gravar em tabelas habilitadas para UniForm. Você deve usar o Databricks Runtime 13.2 ouacima para gravar em tabelas Delta com esse recurso habilitado.

O senhor pode desativar o UniForm desmarcando a propriedade da tabela delta.universalFormat.enabledFormats. O senhor não pode desativar o mapeamento de colunas depois de ativado, e as atualizações para as versões do protocolo de leitura e gravação do Delta Lake não podem ser desfeitas.

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

'delta.universalFormat.enabledFormats' = 'iceberg'

O senhor também deve ativar o mapeamento de colunas e o site IcebergCompatV1 para usar o UniForm. Elas são definidas automaticamente se o senhor ativar o UniForm durante a criação da tabela, como no exemplo a seguir:

SQL
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 colunas, como no exemplo a seguir:

SQL
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:

SQL
ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Quando o senhor ativa o UniForm pela primeira vez, a geração assíncrona de metadados é iniciada. Essa tarefa deve ser concluída antes que clientes externos possam consultar a tabela usando o Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

nota

Se o senhor planeja usar BigQuery como seu cliente leitor Iceberg, deve definir spark.databricks.delta.write.dataFilesToSubdir como true em Databricks para acomodar um requisito BigQuery para disposição de dados.

Consulte Limitações.

Quando o UniForm gera metadados do Iceberg?​

Databricks aciona a geração de metadados Iceberg de forma assíncrona após a conclusão de uma transação de gravação Delta Lake usando o mesmo compute que concluiu a transação Delta. 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 Iceberg, as tabelas Delta com commit frequente podem agrupar vários Delta commits em um único Iceberg commit.

O Delta Lake garante que apenas um processo de geração de metadados do Iceberg esteja em andamento a qualquer momento. O commit que acionaria um segundo processo concorrente de geração de metadados Iceberg será bem-sucedido commit para Delta, mas não acionará 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).

Veja as versões de tabela Delta e Iceberg.

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

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

No Databricks, o senhor 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 Iceberg Reader para saber como revisar as propriedades da tabela fora do Databricks. Para o OSS Apache Spark, o senhor pode ver essas propriedades usando a seguinte sintaxe:

SQL
SHOW TBLPROPERTIES <table-name>;

Acionar manualmente a conversão de metadados do Iceberg​

O senhor 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 em 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 o senhor encontrar o seguinte:

  • Um clustering é encerrado antes que a geração automática de metadados seja bem-sucedida.
  • Um erro ou falha no trabalho interrompe a geração de metadados.
  • Um cliente que não suporta a geração de metadados do UniForm Iceberg grava na tabela Delta.

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

SQL
MSCK REPAIR TABLE <table-name> SYNC METADATA

Veja a TABELA DE REPARO.

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 leitor Iceberg para obter detalhes sobre a 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

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

O senhor também pode usar a API REST para obter todos os detalhes de uma tabela, inclusive 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 seguintes informações:

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

Os clientes do leitor Iceberg baseados em caminhos podem exigir a atualização manual e a renovação dos caminhos JSON dos metadados para ler as versões atuais das tabelas. 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 catálogo Unity Catalog Iceberg endpoint​

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

Os clientes conhecidos por oferecer suporte à API do catálogo Iceberg incluem o Apache Spark, o Flink e o Trino. O senhor deve configurar o acesso ao armazenamento de objetos na nuvem subjacente que contém a tabela Delta com o UniForm ativado. Consulte a documentação do cliente leitor Iceberg para obter detalhes sobre a configuração.

O senhor deve gerar e configurar um Databricks tokens de acesso pessoal para permitir que outros serviços se conectem ao Unity Catalog. Consulte Autorização de acesso ao site Databricks recurso.

A seguir, um exemplo das configurações para configurar o OSS Apache Spark para ler o 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 o URL completo do site workspace no qual o senhor gerou os tokens 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 namespacing de três camadas presente no Unity Catalog, mas acrescenta um prefixo adicional unity.

Versões de mesa Delta e Iceberg​

Tanto o Delta Lake quanto o 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 das tabelas Iceberg e Delta não se alinham pelo carimbo de data/hora do commit ou pelo ID da versão. Se o senhor quiser verificar a qual versão de uma tabela Delta corresponde uma determinada versão de uma tabela Iceberg, poderá usar as propriedades de tabela correspondentes definidas na tabela Iceberg. Consulte Verificar o status de geração de metadados do Iceberg.

Limitações​

Aplicam-se as seguintes limitações:

  • O UniForm não funciona em tabelas com vetores de exclusão ativados. Consulte O que são vetores de exclusão? .
  • As tabelas Delta com o UniForm ativado não são compatíveis com os tipos LIST, MAP e VOID.
  • Os clientes Iceberg só podem ler a partir do UniForm. As gravações não são suportadas.
  • Os clientes do Iceberg Reader podem ter limitações individuais, independentemente do UniForm. Consulte a documentação do cliente escolhido.
  • Iceberg Os clientes de leitura versão 1.2.0 e abaixo não suportam o tipo de registro de data e hora INT96 escrito por Apache Spark. Use o código a seguir no Notebook que grava nas tabelas do UniForm para evitar essa limitação: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • A versão de visualização pública do endpoint Iceberg do Unity Catalog não se destina a cargas de trabalho de produção em grande escala. O senhor poderá sofrer limitação de taxa se exceder o limite de 5 consultas por segundo.

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

  • Alterar feed de dados
  • Delta Sharing
Última atualização em