Usar vetores de exclusão binária em tabelas do Iceberg V3

Os vetores de exclusão binária em tabelas do Apache Iceberg V3 permitem registrar exclusões no nível da linha em arquivos .puffin sem reescrever arquivos de dados inteiros. Em vez de realizar mesclagens caras no momento da consulta, mecanismos como o BigQuery, o Serviço Gerenciado para Apache Spark, o Apache Flink e o Trino usam esses vetores para identificar e pular linhas excluídas durante as leituras.

Com suporte no catálogo do ambiente de execução do Lakehouse, essa otimização pode melhorar o desempenho de gravação e leitura para pipelines de captura de dados alterados (CDC) de alto volume. Ele também ajuda a atender a requisitos regulatórios, como o GDPR (direito de ser esquecido), limpando registros individuais sem a sobrecarga de reescrever arquivos de dados.

Antes de começar

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake, se ainda não tiver feito isso.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar tabelas do Iceberg V3, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Criar e gerenciar tabelas Iceberg V3:
    • Administrador do BigLake (roles/biglake.admin): seu projeto
    • Administrador do Storage (roles/storage.admin): o bucket de destino do Cloud Storage

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar o catálogo REST do Iceberg

Antes de criar uma tabela do Iceberg V3, é necessário configurar o catálogo REST do Iceberg, o que inclui criar um namespace e um catálogo.

A configuração do catálogo REST do Iceberg pode levar algum tempo. Verifique se você criou o namespace e o catálogo antes de continuar.

Limitações

As tabelas do Iceberg V3 no catálogo do ambiente de execução do Lakehouse têm as seguintes limitações:

  • Novos tipos de dados da V3:os novos tipos de dados do Iceberg V3 (como Variant, Geography, carimbo de data/hora em nanossegundos, valores padrão e tipos de dados desconhecidos) não são compatíveis.
  • Rastreamento de linhagem de linha:não há suporte para o rastreamento de linhagem de linha.
  • Gravações do BigQuery:as gravações do BigQuery não são compatíveis com tabelas V3. Só é possível ler tabelas V3 do BigQuery. Para criar e gravar em tabelas V3, use mecanismos de código aberto (como Apache Spark, Apache Flink ou Trino).

Requisitos do mecanismo

Use uma versão do mecanismo que seja compatível com o Iceberg V3 e vetores de exclusão binária. Recomendamos o Apache Spark 3.5 ou mais recente. Os exemplos neste guia usam iceberg-spark-runtime-3.5_2.12:1.10.1.

Ao configurar a sessão da tabela e do mecanismo, verifique o seguinte:

  • Versão do formato da tabela:precisa ser definida como format-version='3'.
  • Modo de exclusão:precisa ser definido como merge-on-read. Esse modo garante que as exclusões sejam gravadas em arquivos separados (os vetores de exclusão), em vez de reescrever os arquivos de dados originais (cópia na gravação).

Exemplo de configuração de sessão do Spark

A configuração a seguir ativa as extensões necessárias do Iceberg e configura a conexão do catálogo REST:

spark-sql \
    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.iceberg:iceberg-gcp:1.10.1 \
    --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-gcp-bundle/1.10.1/iceberg-gcp-bundle-1.10.1.jar \
    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
    --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
    --conf spark.sql.catalog.CATALOG_NAME.type=rest \
    --conf spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog \
    --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH \
    --conf spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID \
    --conf spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager \
    --conf spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO \
    --conf spark.sql.defaultCatalog=CATALOG_NAME

Substitua:

  • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
  • WAREHOUSE_PATH: o URI da pasta do Cloud Storage em que o data warehouse está armazenado, começando com gs://.
  • PROJECT_ID: o ID do projeto Google Cloud .

Usar vetores de exclusão binária

Para usar vetores de exclusão binária em tabelas do Apache Iceberg V3, crie uma tabela com a versão de formatação 3, preencha a tabela com dados, faça modificações padrão no banco de dados e consulte a tabela. É possível executar todas as instruções de criação, inserção, exclusão e atualização usando o Spark SQL.

Criar uma tabela Iceberg com vetores de exclusão binária

Crie uma tabela especificando format-version='3' e os modos de exclusão, atualização e mesclagem merge-on-read nas propriedades da tabela. Execute a seguinte instrução no Spark SQL:

Spark 

CREATE NAMESPACE IF NOT EXISTS my_namespace;
USE my_namespace;

CREATE TABLE my_namespace.mytable_v3 (
   id BIGINT,
   city STRING,
   state STRING
) TBLPROPERTIES (
   'format-version'='3',
   'write.delete.mode'='merge-on-read',
   'write.update.mode'='merge-on-read',
   'write.merge.mode'='merge-on-read'
);

Fazer upgrade de uma tabela do Iceberg V2 para V3

É possível fazer upgrade de uma tabela Iceberg V2 para V3 usando instruções ALTER TABLE. Não é possível fazer downgrade de uma tabela da V3 para a V2. Execute a seguinte instrução no Spark SQL:

Spark 

ALTER TABLE my_namespace.mytable_v2 SET TBLPROPERTIES ('format-version' = '3');

Inserir dados na tabela

Para garantir que os arquivos de vetor de exclusão binária sejam gerados para exclusões, o mecanismo não pode voltar para a cópia em gravação. Isso geralmente requer uma quantidade significativa de dados na tabela antes da operação de exclusão. Por exemplo, o Apache Spark pode otimizar pequenas exclusões voltando para a cópia em gravação. Preencha a tabela executando as seguintes instruções no Spark SQL:

Spark 

-- Create a temporary view with a large number of rows (100,000 rows)
CREATE OR REPLACE TEMPORARY VIEW large_source AS
SELECT
  id,
  CAST(id AS STRING) as city,
  'WA' as state
FROM (
  SELECT row_number() OVER (ORDER BY (SELECT NULL)) as id
  FROM (SELECT 0 FROM range(1000)) a
  CROSS JOIN (SELECT 0 FROM range(100)) b
);

-- Overwrite the existing table with the generated data
INSERT OVERWRITE my_namespace.mytable_v3 SELECT * FROM large_source;

Excluir dados

Execute uma instrução DELETE no Spark SQL. Como a tabela está configurada para merge-on-read e tem dados suficientes, o Spark gera arquivos de exclusão usando vetores de exclusão binários.

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Atualizar dados

Executar uma instrução UPDATE no Spark SQL. Como a tabela está configurada para merge-on-read e tem dados suficientes, o Spark gera arquivos de exclusão usando vetores de exclusão binários.

Spark 

UPDATE my_namespace.mytable_v3 SET state = 'NY' WHERE id = 1;

consulte a tabela

As consultas na tabela usam automaticamente os arquivos de vetor de exclusão binária para excluir linhas excluídas. É possível consultar a tabela usando o Apache Spark ou o BigQuery.

Spark 

-- Should be less than the initial 100,000 rows
SELECT count(*) FROM my_namespace.mytable_v3;

-- Should return no results
SELECT * FROM my_namespace.mytable_v3 WHERE id = 5000;

-- Should return 'NY'
SELECT * FROM my_namespace.mytable_v3 WHERE id = 1;

BigQuery

Ao consultar o BigQuery, use o identificador de tabela totalmente qualificado PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3.

bq query --nouse_legacy_sql \
    'SELECT * FROM `PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3` LIMIT 10'

Verificar a criação de vetores de exclusão binária

Para verificar se os vetores de exclusão binária foram criados, inspecione o diretório de armazenamento e os metadados do snapshot.

Verificar se há arquivos .puffin

Navegue até o diretório de dados da tabela no seu warehouse do Cloud Storage (por exemplo, gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data). Você vai encontrar arquivos .puffin, que armazenam os vetores de exclusão binários.

Analisar metadados de snapshot

Os metadados do snapshot nos arquivos JSON da tabela do Iceberg contêm informações sobre a operação de exclusão. Procure propriedades como added-delete-files, added-dvs e operation no resumo do snapshot. Isso confirma que os arquivos de exclusão foram adicionados.

"summary": {
  "operation": "delete",
  "added-delete-files": "1",
  "added-dvs": "1",
  "added-files-size": "42",
  "added-position-deletes": "1",
  ...
}

A seguir