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

O catálogo do ambiente de execução do Lakehouse oferece suporte a tabelas do Apache Iceberg V3. Um recurso principal da especificação do Apache Iceberg V3 são os vetores de exclusão binários. Essa otimização armazena exclusões no nível da linha em arquivos .puffin. Em vez de realizar junções caras no momento da consulta, o BigQuery e mecanismos de código aberto (como Apache Spark, Apache Flink e Trino) usam esses vetores para identificar e ignorar rapidamente as linhas excluídas.

O uso de vetores de exclusão binários pode melhorar o desempenho das seguintes maneiras:

  • Gravações de alto volume:melhora o desempenho de gravação para tabelas com gravações de alto volume.
  • Leituras eficientes:melhora a velocidade da consulta, permitindo que o BigQuery e mecanismos de código aberto identifiquem e ignorem as linhas excluídas.

Isso é particularmente útil para processar atualizações e exclusões de alto volume em pipelines de captura de dados alterados (CDC, na sigla em inglês) ou para atender a requisitos regulamentares, como o GDPR (direito de ser esquecido), excluindo linhas específicas sem o overhead de reescrever arquivos de dados inteiros.

Antes de começar

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

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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:

  • Todos:
    • Administrador do BigLake (roles/biglake.admin) – seu projeto
    • Administrador do Storage (roles/storage.admin) – o bucket do Cloud Storage de destino

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 personalizados papéis ou outros predefinidos papéis.

Configurar o catálogo REST do Iceberg

Antes de criar uma tabela do Iceberg V3, é necessário configurar o catálogo REST do Iceberg, que inclui a criação de 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 V3:novos tipos de dados do Iceberg V3 (como variante, geografia, carimbo de data/hora de nanossegundos, valores padrão e tipos de dados desconhecidos) não são aceitos.
  • Rastreamento de linhagem de linhas:o rastreamento de linhagem de linhas está indisponível.
  • Gravações do BigQuery:as gravações do BigQuery não são aceitas com tabelas V3. Só é possível ler tabelas V3 do BigQuery. Para criar e gravar em tabelas V3, é necessário usar mecanismos de código aberto (como Apache Spark, Apache Flink ou Trino).

Requisitos do mecanismo

Verifique se você está usando uma versão do mecanismo que oferece suporte ao Iceberg V3 e aos vetores de exclusão binários. 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 tabela e a sessão 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 Google Cloud projeto.

Usar vetores de exclusão binários

Para usar vetores de exclusão binários em tabelas do Apache Iceberg V3, é necessário criar uma tabela com a versão de formatação 3, preencher a tabela com dados, realizar modificações padrão do banco de dados e consultar 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 do Iceberg com vetores de exclusão binários

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 instrução a seguir 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 do 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 instrução a seguir 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ários sejam gerados para exclusões, o mecanismo não pode voltar para a cópia na gravação. Isso normalmente exige que uma quantidade significativa de dados esteja presente na tabela antes da operação de exclusão. Por exemplo, o Apache Spark pode otimizar pequenas exclusões voltando para a cópia na 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

Execute 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ários 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 no 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ários

É possível verificar se os vetores de exclusão binários foram criados inspecionando o diretório de armazenamento e os metadados do snapshot.

Verificar arquivos .puffin

Navegue até o diretório de dados da tabela no data 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.

Examinar metadados do 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