Pular para o conteúdo principal
Última atualização em

Use o recurso Apache Iceberg v3

O Apache Iceberg v3 aprimora o desempenho de query e introduz novos recursos para tabelas gerenciadas usando Iceberg ou Delta Lake com leituras Iceberg no Unity Catalog.

Os key recursos do Iceberg v3 são:

Requisitos​

Para usar tabelas gerenciadas com recursos do Iceberg v3, como tipos geoespaciais, você deve atender aos seguintes requisitos:

  • Um workspace com o Unity Catalog habilitado.
  • Databricks Runtime 18 LTS e acima.

Crie uma nova tabela com o Iceberg v3​

Crie novas tabelas com o Iceberg v3 habilitado tanto para tabelas Delta Lake gerenciadas com leituras Iceberg quanto para tabelas Iceberg gerenciadas.

Para criar uma nova tabela gerenciada usando Delta Lake com leituras Iceberg e Iceberg v3 ativados, use o seguinte comando SQL:

SQL
CREATE OR REPLACE TABLE main.schema.table (c1 INT) TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'delta.enableIcebergCompatV3' = 'true'
);

Para obter mais informações sobre leituras do Iceberg, consulte Ler tabelas Delta Lake com clientes Iceberg.

Atualize uma tabela existente para Iceberg v3.​

Você pode atualizar uma tabela existente para o Iceberg v3 da seguinte forma:

  1. Habilitar qualquer recurso da versão 3 em uma tabela.
  2. Definindo a versão do formato Iceberg em uma tabela para 3 (mostrada abaixo).
info

As tabelas podem ser rebaixadas da versão 3 para a versão 2 restaurando a tabela para uma versão anterior à atualização para a versão 3 usando RESTORE. Consulte Fazer downgrade de uma tabela para uma versão anterior.

Para atualizar uma tabela gerenciada usando Delta Lake com leituras de Iceberg para a v3, use o seguinte comando:

SQL
ALTER TABLE catalog.schema.table SET TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.enableIcebergCompatV2' = 'false'
);

Habilitar vetores de exclusão​

Os vetores de exclusão otimizam as operações de modificação de dados em nível de linha e estão ativados por default em todas as novas tabelas Iceberg v3. Consulte Vetores de exclusão no Databricks.

nota

Habilitar vetores de exclusão em uma tabela Iceberg existente atualiza a versão do formato Iceberg para 3.

Para criar uma nova tabela gerenciada usando Delta Lake com leituras Iceberg, Iceberg v3 e vetores de exclusão ativados, defina as seguintes propriedades de tabela:

SQL
CREATE TABLE catalog.schema.table (c1 INT) TBLPROPERTIES(
  'delta.enableDeletionVectors' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Use o tipo de dados VARIANT.​

O tipo de dados VARIANT permite armazenar e consultar dados semiestruturados.

nota

Usar VARIANT em uma tabela Iceberg existente atualiza a versão do formato Iceberg para 3.

Para criar uma nova tabela gerenciada usando Delta Lake com leituras Iceberg e uma coluna VARIANT:

SQL
CREATE TABLE catalog.schema.deltaTable (col VARIANT) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Para adicionar uma coluna VARIANT a uma tabela existente, use o comando ALTER TABLE :

SQL
ALTER TABLE catalog.schema.table ADD COLUMN variant_col VARIANT;

Use tipos de dados GEOMETRY e GEOGRAPHY​

Use os tipos de dados GEOMETRY e GEOGRAPHY para armazenar e consultar dados geoespaciais. Veja tipoGEOMETRY e tipoGEOGRAPHY.

nota

O uso de GEOMETRY ou GEOGRAPHY em uma tabela Iceberg existente atualiza a versão do formato Iceberg para 3.

Para criar uma nova tabela gerenciada usando o Delta Lake com leituras do Iceberg e colunas GEOMETRY ou GEOGRAPHY:

SQL
CREATE TABLE catalog.schema.table (
  geom_col GEOMETRY(3857),
  geog_col GEOGRAPHY(4326)
) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Para adicionar uma coluna GEOMETRY ou GEOGRAPHY a uma tabela existente, use o comando ALTER TABLE:

SQL
ALTER TABLE catalog.schema.table ADD COLUMN geom_col GEOMETRY(3857);
ALTER TABLE catalog.schema.table ADD COLUMN geog_col GEOGRAPHY(4326);

Criar uma tabela com default de gravação​

O Iceberg v3 define dois tipos de valores default:

  • Padrões de gravação aplicam-se a novas linhas quando uma gravação omite a coluna correspondente. O Databricks oferece suporte a padrões de gravação.
  • Padrões iniciais aplicam-se a linhas preexistentes quando uma nova coluna é adicionada. O Databricks não oferece suporte a padrões iniciais.

Para criar uma nova tabela gerenciada usando Delta Lake com leituras do Iceberg e um default de gravação:

SQL
CREATE TABLE catalog.schema.table (
  id INT,
  row_status STRING DEFAULT 'active'
) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Para ver o default aplicado, insira uma linha sem row_status:

SQL
INSERT INTO catalog.schema.table (id) VALUES (1);
SELECT * FROM catalog.schema.table;

A query anterior retorna o seguinte, com o default aplicado a row_status:

Output
id  row_status
1   active

Reverter uma tabela para uma versão anterior do Apache Iceberg.​

Se você precisar reverter uma tabela para um estado anterior à atualização para o Iceberg v3, você pode usar o comando RESTORE .

SQL
set spark.databricks.delta.restore.protocolDowngradeAllowed = true;
RESTORE TABLE catalog.schema.table TO VERSION AS OF 1;
set spark.databricks.delta.restore.protocolDowngradeAllowed = false;

Limitações​

O Databricks é compatível com a versão 3 da especificação Iceberg, com as seguintes exceções:

  • Defaults iniciais não são aceitos. Quando uma nova coluna é adicionada, um default inicial define o valor para as linhas preexistentes.

  • Os seguintes tipos de dados não são suportados:

    • Tipo desconhecido
    • Carimbo de data/hora com precisão de nanossegundos.

  • Transformações com múltiplos argumentos não são suportadas.

  • Clientes externos do Iceberg não podem commit arquivos de exclusão de igualdade em tabelas Iceberg gerenciadas por meio do catálogo REST do Iceberg. Para alterações de nível de linha (DELETE, UPDATE ou MERGE), o cliente deve usar o modo copy-on-write ou registrar linhas excluídas como vetores de exclusão. Consulte limitações do catálogo REST do Iceberg.

Nesta página