Tecnologias/04 - Armazenamento de Objetos/03 - Apache Iceberg3 min

Iceberg no S3 e no R2 - Catálogos e Motores

O que cada componente faz

Uma tabela Iceberg precisa de arquivos, metadados e um mecanismo para localizar e publicar seu estado. O bucket conserva objetos; o catálogo apresenta tabelas e coordena commits; o motor executa consultas e alterações que sua integração suporta.

flowchart LR
    A[Aplicação SQL] --> M[Motor de consulta]
    M -->|Localiza tabela e publica commit| C[Catálogo]
    C -->|Referência aos metadados atuais| M
    M -->|Lê e grava metadados e dados| O[S3 ou R2]

O desenho representa responsabilidades lógicas. Um catálogo pode fornecer credenciais temporárias ou realizar outras tarefas conforme sua implementação. O protocolo REST padroniza interações; não transforma todos os catálogos em serviços idênticos. Referência: especificação do catálogo REST.

Por que apontar para um bucket não basta

Configurar endpoint e credencial resolve acesso ao armazenamento. Ainda é necessário descobrir a tabela correta, interpretar sua versão do formato e usar o catálogo adequado para publicar alterações. Listar arquivos Parquet diretamente ignora snapshots e pode incluir arquivos substituídos, órfãos ou sujeitos a exclusões registradas nos metadados.

No Spark, configurações do catálogo e da implementação de acesso a arquivos são partes da integração. Cada ambiente precisa associar nome lógico, catálogo, autenticação e armazenamento. Um comando SQL sem esse contexto não é um exemplo executável completo. Referência: configuração no Spark.

Usar S3 ou R2

Decisão	O que conferir
Endpoint e credenciais	O cliente acessa o serviço realmente escolhido
Operações de objetos	A integração usa somente operações e parâmetros suportados
Catálogo	Todos os escritores coordenam a mesma tabela pelo mecanismo correto
Motor e formato	Leitura, escrita, deletes e evolução são suportados nas versões usadas
Local do processamento	Rede e distância até os objetos entram no custo e na latência

Compatibilidade S3 do R2 não implica equivalência de todos os recursos de bucket. A Cloudflare também oferece R2 Data Catalog para tabelas Iceberg; capacidades e integrações devem ser conferidas na documentação correspondente. Matriz S3 do R2 e R2 Data Catalog.

Aprofundamento aplicado

Migrar arquivos não migra automaticamente uma tabela

Considere copiar objetos de um bucket S3 para R2. Metadados podem conter localizações dos arquivos originais, e o catálogo pode continuar apontando para o estado anterior. Uma migração precisa usar um procedimento compatível com o formato e as ferramentas, preservando referências e coordenando escritores durante a mudança.

Criar dois catálogos independentes para os mesmos arquivos não garante uma decisão única de commit. Eles podem publicar histórias divergentes. Defina qual catálogo é autoridade para a tabela e como leitores e escritores passam ao novo ambiente.

Exercício de integração

Em um ambiente de estudo:

Crie uma tabela pelo catálogo escolhido e insira um lote pequeno.
Leia pelo segundo motor usando o mesmo catálogo e registre o snapshot.
Faça uma alteração suportada e verifique o estado atual e o histórico preservado.
Simule falha antes de publicar um commit e identifique os arquivos não referenciados.

Resultado esperado: os motores concordam sobre a versão publicada; uma simples listagem do bucket pode conter mais arquivos do que a tabela atual utiliza. Se o segundo motor não suporta determinada alteração ou versão, registre a limitação.

Relacionado: 1. Iceberg por Dentro - Metadados, Snapshots e Commits · 3. Iceberg - Time Travel, Deletes e Manutenção · 3. Parquet e S3 com DuckDB.