Acessar dados do Iceberg no AlloyDB

Pré-lançamento — acesso direto ao Iceberg

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O acesso direto ao Iceberg no AlloyDB para PostgreSQL permite consultar dados armazenados no formato de tabela do Apache Iceberg no Cloud Storage pela instância do AlloyDB. É possível acessar conjuntos de dados do Iceberg usando URIs de bucket do Cloud Storage ou o catálogo do ambiente de execução do Lakehouse. Para acelerar as cargas de trabalho analíticas, o AlloyDB oferece um mecanismo colunar integrado que otimiza verificações, mesclagens e agregações. Ao se integrar ao mecanismo colunar, o acesso direto ao Iceberg permite executar consultas analíticas de alto desempenho no seu data lakehouse sem criar, gerenciar ou manter pipelines de dados complexos de extração, transformação e carregamento (ETL).

É possível consultar tabelas do Iceberg usando comandos SQL padrão, mesclar conjuntos de dados do Iceberg com tabelas operacionais no AlloyDB e preencher tabelas do Iceberg no mecanismo colunar na memória para acelerar o desempenho da consulta.

Vantagens

O acesso direto ao Iceberg oferece os seguintes benefícios:

• Acesso ao lakehouse sem ETL: consulte conjuntos de dados externos do Iceberg no local sem copiar ou mover dados para sistemas analíticos separados.
• Consultas transacionais e analíticas unificadas: mescle dados operacionais em tempo real armazenados em tabelas de heap do AlloyDB com dados históricos massivos armazenados em tabelas do Iceberg no Cloud Storage.
• Integração flexível de catálogos: acesse metadados de tabelas do Iceberg em caminhos de bucket do Cloud Storage ou pelo catálogo de ambiente de execução do Lakehouse.
• Aceleração de consultas colunares: armazene em cache e preencha tabelas do Iceberg na memória do mecanismo colunar do AlloyDB para processamento analítico em menos de um segundo.
• Interface SQL padrão: use a sintaxe conhecida do PostgreSQL para consultar e analisar tabelas do Iceberg.

Como funciona o acesso direto ao Iceberg

O acesso direto ao Iceberg usa a interface do método de acesso à tabela (TAM, na sigla em inglês) do PostgreSQL (USING iceberg) e se integra ao planejador e ao framework de execução do mecanismo colunar do AlloyDB.

Ao consultar uma tabela do Iceberg, o AlloyDB opera em um dos seguintes modos:

• Verificação direta (para leituras de streaming): o AlloyDB lê os metadados e os arquivos de dados mais recentes diretamente do Cloud Storage. O mecanismo colunar processa os dados em streaming.
• Aceleração do mecanismo colunar (para leituras em cache na memória): quando você preenche uma tabela do Iceberg no mecanismo colunar do AlloyDB usando a função google_columnar_engine_add(), a tabela é carregada no armazenamento colunar na memória. As consultas subsequentes são lidas na memória do mecanismo colunar, maximizando a capacidade de processamento de consultas e minimizando a latência.

Disponibilização de snapshots e atualização de cache

O snapshot da tabela do Iceberg que o AlloyDB consulta depende do modo de leitura:

• Verificação direta: o AlloyDB executa consultas no snapshot mais recente do Iceberg. Quando uma consulta é iniciada, o AlloyDB determina o snapshot mais recente disponível da tabela do Iceberg e lê os dados desse snapshot, mesmo em uma transação REPEATABLE READ ou SERIALIZABLE. O AlloyDB não é compatível com a fixação de snapshots e consultas pontuais em transações.

  Por exemplo, quando você consulta uma tabela usando a verificação direta, cada instrução em uma transação lê o snapshot mais recente disponível:

  BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
  SELECT * FROM customer_orders;
  -- If an external process commits a new Iceberg snapshot:
  SELECT * FROM customer_orders; -- Returns results from the new snapshot.
  COMMIT;
  

• Aceleração do mecanismo colunar: o AlloyDB executa consultas no snapshot preenchido no mecanismo colunar. Se o AlloyDB gravar novos dados na tabela Iceberg subjacente no Cloud Storage após o preenchimento, as consultas poderão retornar dados desatualizados. Para receber dados atualizados após operações de DML na tabela, atualize o cache usando a função google_columnar_engine_refresh().

Tipos de dados compatíveis

Ao definir uma tabela do Iceberg no AlloyDB, os nomes das colunas e os tipos de dados na instrução DDL precisam corresponder aos tipos no esquema do Iceberg.

O acesso direto ao Iceberg é compatível com os seguintes tipos de dados do Apache Iceberg e os tipos correspondentes do AlloyDB:

Tipo de dados do Apache Iceberg	Tipo de dados do AlloyDB	Descrição
boolean	BOOLEAN	Conversão vetorizada para o formato de bytes compactados
int	INT / INTEGER	Número inteiro assinado de 32 bits
long	BIGINT	Inteiro assinado de 64 bits
float	REAL / FLOAT4	Ponto flutuante de precisão única de 32 bits
double	DOUBLE PRECISION / FLOAT8	Ponto flutuante de precisão dupla de 64 bits
decimal(P, S)	NUMERIC(P, S) / DECIMAL(P, S)	Valor numérico de ponto fixo com precisão P e escala S
string	TEXT / VARCHAR	Valores de string UTF-8
date	DATE	Data do calendário (ano, mês, dia)
timestamp	TIMESTAMP	Carimbo de data/hora sem fuso horário
timestamptz	TIMESTAMPTZ	Carimbo de data/hora com fuso horário

Limitações

O acesso direto ao Iceberg tem as seguintes limitações:

• Disponibilidade da versão do PostgreSQL: o AlloyDB é compatível com o acesso direto ao Iceberg no PostgreSQL 18 e versões mais recentes.
• Permissões de usuário: somente usuários do banco de dados com o papel alloydbsuperuser podem criar tabelas do Iceberg. Depois que uma tabela é criada, é possível conceder permissões SELECT a outros usuários para consultar a tabela do Iceberg.
• Operações somente leitura: o AlloyDB é compatível apenas com consultas SELECT (DQL) em tabelas do Iceberg. Ele não é compatível com operações de gravação (INSERT, UPDATE, DELETE, TRUNCATE).
• Versão da especificação do Apache Iceberg: o AlloyDB não é compatível com arquivos de exclusão do Iceberg v2 (exclusões posicionais e de igualdade) ou vetores de exclusão do Iceberg v3.
• Suporte a formatos de arquivo: o acesso direto ao Iceberg é compatível com arquivos de dados Parquet e arquivos de metadados JSON e Avro. Ele não é compatível com arquivos de dados ORC.
• Controle de versões de snapshot: as consultas de verificação direta são executadas no snapshot mais recente da tabela do Iceberg, e as consultas aceleradas por colunas são executadas no snapshot preenchido. O AlloyDB não oferece suporte a consultas pontuais.
• Evolução do esquema: o AlloyDB não oferece suporte a operações ALTER TABLE em tabelas do Iceberg. A tabela do Iceberg não pode ter passado por uma migração de esquema.
• Suporte ao catálogo de metadados: o acesso direto ao Iceberg é compatível com caminhos diretos de bucket do Cloud Storage (gs://) e caminhos de catálogo do ambiente de execução do Lakehouse (bl://). Para o catálogo do ambiente de execução do Lakehouse, o AlloyDB é compatível apenas com o modo de credenciais do usuário final. Ele não é compatível com o modo de venda de credenciais ou outros catálogos REST.
• Buckets de pagamentos do solicitante: o AlloyDB não é compatível com buckets do Cloud Storage que usam Pagamentos do solicitante.
• Restrição de preenchimento total: o AlloyDB não é compatível com o preenchimento colunar parcial para tabelas do Iceberg. As tabelas precisam caber na memória do mecanismo colunar ou no espaço do SSD.
• Memória de heap de população: preencher uma tabela do Iceberg que contém grandes grupos de linhas do Parquet pode exceder o limite de memória de heap de população por worker, especialmente em instâncias com menos vCPUs. Para resolver esse problema, consulte O heap de população do mecanismo colunar está cheio.

Antes de começar

Antes de criar e consultar tabelas do Iceberg, conclua o seguinte:

1. Crie um cluster do AlloyDB executando o PostgreSQL 18 ou posterior no Google Cloud. Para mais informações, consulte Criar um cluster.
2. Hospedar uma tabela do Apache Iceberg no Cloud Storage ou registrada no catálogo do ambiente de execução do Lakehouse:
   • Para caminhos do Cloud Storage, a estrutura de diretórios do bucket precisa seguir o layout padrão do Apache Iceberg, que contém os subdiretórios data/ e metadata/, incluindo arquivos JSON de metadados e version-hint.text. Para mais informações, consulte Criar um bucket.
   • Para o catálogo do ambiente de execução do Lakehouse, crie e registre seu catálogo do Iceberg no modo de credenciais de usuário final. Para mais informações, consulte Configurar o endpoint do catálogo REST do Apache Iceberg.
3. Configure as credenciais do banco de dados para um usuário com o papel alloydbsuperuser. Para mais informações, consulte Papel do grupo alloydbsuperuser.

Funções exigidas

Para permitir que o AlloyDB leia dados e metadados do Iceberg, conceda os papéis do IAM necessários à conta de serviço do cluster do AlloyDB:

• Acesso ao Cloud Storage: conceda o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket do Cloud Storage que contém os dados e metadados do Iceberg.
• Acesso ao BigLake (se estiver usando o catálogo do ambiente de execução do Lakehouse): conceda o papel de Leitor do BigLake (roles/biglake.viewer) no projeto que hospeda o catálogo do BigLake.

Para encontrar a conta de serviço do cluster, execute o comando gcloud beta alloydb clusters describe:

gcloud beta alloydb clusters describe CLUSTER_ID --region=REGION_ID

Substitua:

• CLUSTER_ID: o ID do cluster do AlloyDB.
• REGION_ID: o local do cluster do AlloyDB. Por exemplo, us-east1. Para uma lista completa de regiões, consulte Locais do AlloyDB.

A saída contém um campo serviceAccountEmail, que é a conta de serviço desse cluster. No console do Google Cloud , é possível encontrar a conta de serviço na página Visão geral do cluster.

Para conceder o papel de Leitor de Objetos do Storage usando a CLI gcloud, execute:

gcloud storage buckets add-iam-policy-binding \
    gs://BUCKET_NAME \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Se você usar o catálogo do ambiente de execução do Lakehouse, conceda o papel de Leitor do BigLake:

gcloud projects add-iam-policy-binding LAKEHOUSE_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/biglake.viewer"

Substitua:

• BUCKET_NAME: o nome do bucket do Cloud Storage.
• LAKEHOUSE_PROJECT_ID: o ID do projeto do Google Cloud em que o catálogo do ambiente de execução do Lakehouse está hospedado.
• SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço do cluster que você encontrou no campo serviceAccountEmail.

Configurar flags de bancos de dados

Para ativar o mecanismo colunar e o acesso direto ao Iceberg, configure as flags de banco de dados na instância do AlloyDB. Defina as seguintes flags de banco de dados na instância:

Flag de banco de dados	Valor	Descrição
google_columnar_engine.enabled	on	Ativa o mecanismo colunar do AlloyDB.
google_columnar_engine.enable_iceberg_reads	on	Ativa o acesso direto ao Iceberg. É necessário reiniciar a instância.
google_columnar_engine.memory_size_in_mb	SIZE_IN_MB	(Opcional) Aloca memória para o mecanismo colunar. Recomendado se você planeja preencher tabelas do Iceberg na memória.

Para configurar essas flags usando a CLI gcloud, execute o comando gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_iceberg_reads=on

Substitua:

• INSTANCE_ID: o ID da instância do AlloyDB.
• CLUSTER_ID: o ID do cluster do AlloyDB.
• REGION_ID: o ID da região do cluster do AlloyDB.

Criar uma tabela Iceberg no AlloyDB

Para expor um conjunto de dados do Apache Iceberg no AlloyDB, conecte-se como um usuário com privilégios alloydbsuperuser. Em seguida, crie uma tabela usando o método de acesso à tabela USING iceberg.

CREATE TABLE TABLE_NAME (
    COLUMN_NAME DATA_TYPE [, ...]
)
USING iceberg
WITH (
    uri = 'LOCATION_URI'
);

Substitua:

• TABLE_NAME: o nome da tabela a ser criada no AlloyDB.
• COLUMN_NAME e DATA_TYPE: as definições da coluna. Os nomes e tipos de colunas precisam corresponder ao esquema da tabela do Iceberg subjacente.
• LOCATION_URI: o local dos metadados da tabela Iceberg. Especifique um dos seguintes formatos:
  • Caminho direto do Cloud Storage: gs://BUCKET_NAME/PATH_TO_ICEBERG_TABLE
  • URI do catálogo do ambiente de execução do Lakehouse: bl://projects/PROJECT_ID/catalogs/CATALOG_NAME/databases/DATABASE_NAME/tables/TABLE_NAME

Exemplos

Os exemplos a seguir mostram como criar tabelas do Iceberg no AlloyDB.

Criar uma tabela com base em um caminho do Cloud Storage

O exemplo a seguir cria uma tabela chamada customer_orders com o suporte de um conjunto de dados do Iceberg localizado em um bucket do Cloud Storage:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'gs://my-iceberg-analytics-bucket/datasets/sales/customer_orders'
);

Criar uma tabela do catálogo do ambiente de execução do Lakehouse

O exemplo a seguir cria uma tabela que faz referência a uma tabela do Iceberg gerenciada pelo catálogo do ambiente de execução do Lakehouse:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'bl://projects/my-analytics-project/catalogs/sales_catalog/databases/retail_db/tables/customer_orders'
);

Consultar dados do Iceberg

Depois de criar a tabela no AlloyDB, é possível consultá-la usando instruções SQL padrão SELECT com privilégios alloydbsuperuser. Se quiser, você pode conceder permissões de leitura a um usuário sem privilégios alloydbsuperuser usando a instrução GRANT. Por exemplo, GRANT SELECT ON customer_orders TO normal_user.

Consultar dados

O exemplo a seguir mostra como executar uma consulta:

SELECT
    customer_id,
    COUNT(order_id) AS total_orders,
    SUM(total_amount) AS total_spent
FROM customer_orders
WHERE is_completed = true
  AND order_date >= '2026-01-01'
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10;

Consultar dados conjuntos do Iceberg com dados operacionais

É possível combinar dados operacionais em tempo real que residem no AlloyDB com dados históricos que residem no Iceberg:

SELECT
    c.customer_name,
    c.account_tier,
    COUNT(o.order_id) AS total_orders,
    SUM(o.total_amount) AS historical_spend
FROM customer_orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.is_completed = true
GROUP BY c.customer_name, c.account_tier
ORDER BY historical_spend DESC;

Importar dados para uma tabela local

Para criar uma cópia independente e gravável dos dados do Iceberg no armazenamento local do AlloyDB, execute CREATE TABLE ... AS SELECT, conforme mostrado no exemplo a seguir:

CREATE TABLE local_customer_orders AS
SELECT * FROM customer_orders
WHERE order_date >= '2026-01-01';

Acelerar consultas usando o mecanismo colunar

Para cargas de trabalho analíticas que exigem latência ultrabaixa, é possível preencher a tabela do Iceberg diretamente na memória do mecanismo colunar do AlloyDB.

Preencher a tabela do Iceberg no armazenamento colunar

Para preencher todas as colunas de uma tabela do Iceberg no mecanismo colunar do AlloyDB, use a função google_columnar_engine_add(). Exemplo:

SELECT google_columnar_engine_add('customer_orders');

Para preencher apenas colunas específicas usadas pelas consultas, transmita uma lista separada por vírgulas de nomes de colunas como o segundo argumento. Exemplo:

SELECT google_columnar_engine_add('customer_orders', 'customer_id,order_status');

Para mais informações, consulte Adicionar colunas usando funções SQL.

Atualizar dados preenchidos

Se você gravar novos snapshots no conjunto de dados do Iceberg, atualize a tabela para recarregar os dados mais recentes no mecanismo colunar para que as consultas retornem resultados atualizados:

SELECT google_columnar_engine_refresh('customer_orders');

Remover uma tabela do armazenamento colunar

Para remover uma tabela do Iceberg do armazenamento colunar e voltar à verificação direta:

SELECT google_columnar_engine_drop('customer_orders');

Monitorar e verificar a execução de consultas

É possível monitorar como o AlloyDB executa consultas em tabelas do Iceberg e verificar se as consultas usam o mecanismo colunar na memória. Use as visualizações do sistema para verificar o status de preenchimento do cache e use EXPLAIN para inspecionar os planos de execução de consultas.

Verificar o status do armazenamento em cache colunar

Para verificar se uma tabela do Iceberg está preenchida no mecanismo colunar, consulte a visualização do sistema g_columnar_relations:

SELECT relation_name, status
FROM g_columnar_relations
WHERE relation_name = 'customer_orders';

Um valor status de USABLE confirma que a tabela está armazenada em cache na memória do mecanismo colunar.

Inspecionar planos de execução de consultas com EXPLAIN

Para verificar se uma consulta usa o mecanismo colunar, use a instrução EXPLAIN:

EXPLAIN (ANALYZE, COSTS OFF)
SELECT SUM(total_amount)
FROM customer_orders
WHERE is_completed = true;

A saída indica a execução colunar por meio de um nó Custom Scan (ColumnarScan) na tabela:

Custom Scan (ColumnarScan) on customer_orders
  Filter: (is_completed = true)

Solução de problemas

Nesta seção, descrevemos como resolver problemas comuns ao configurar e consultar tabelas do Iceberg no AlloyDB.

A flag google_columnar_engine.enable_iceberg_reads está desativada

Causa: a flag de banco de dados para acesso direto ao Iceberg está desativada.

Correção recomendada: defina as flags de banco de dados google_columnar_engine.enabled=on e google_columnar_engine.enable_iceberg_reads=on na instância e reinicie-a.

A permissão para acessar o Cloud Storage foi negada.

Causa: a conta de serviço do cluster do AlloyDB não tem acesso de leitura ao bucket do Cloud Storage.

Correção recomendada: conceda o papel roles/storage.objectViewer à conta de serviço do cluster no bucket.

Permissão negada para acessar o catálogo do ambiente de execução do Lakehouse

Causa: a conta de serviço do cluster do AlloyDB não tem acesso de leitura ao catálogo do ambiente de execução do Lakehouse.

Correção recomendada: conceda o papel roles/biglake.viewer à conta de serviço do cluster no projeto do Google Cloud que hospeda o catálogo do ambiente de execução do Lakehouse.

Falha na população colunar

Causa: o tamanho da tabela do Iceberg excede a memória disponível e o espaço SSD no mecanismo colunar.

Correção recomendada: aumente a alocação de memória para o mecanismo colunar usando a flag google_columnar_engine.memory_size_in_mb na instância ou aumente o tamanho do cache de armazenamento do mecanismo colunar usando a flag google_columnar_engine.storage_cache_size. Para mais informações, consulte Configurar o cache de armazenamento para o mecanismo colunar.

O heap de população do mecanismo colunar está cheio

Mensagem de erro:

ERROR: Columnar engine population heap is full during population. Set
google_columnar_engine.population_heap_size_in_mb to a bigger value.

Causa: a memória necessária para preencher um grande grupo de linhas do Parquet excede o limite de heap de população por worker.

Correção recomendada: reduza o número de workers de preenchimento paralelos para que o processo de preenchimento possa usar um heap maior. Na sessão SQL em que você preenche a tabela, defina a flag google_job_scheduler.max_parallel_workers_per_job como 0 antes de chamar a função google_columnar_engine_add():

SET google_job_scheduler.max_parallel_workers_per_job = 0;
SELECT google_columnar_engine_add('TABLE_NAME');

Substitua TABLE_NAME pelo nome da tabela do Iceberg no AlloyDB.

A seguir

• Aprenda mais sobre o mecanismo colunar do AlloyDB.
• Saiba como configurar o mecanismo colunar.
• Escolha como acessar os dados do BigQuery no AlloyDB.