Iceberg por Dentro - Metadados, Snapshots e Commits

O problema de uma pasta cheia de Parquet

Imagine uma tabela representada por três arquivos. Um processo substitui dois deles, outro adiciona um quarto e uma consulta começa no meio dessas operações. Listar o bucket pode mostrar objetos perfeitamente atuais e ainda assim não definir uma versão coerente da tabela: falta dizer quais arquivos pertencem ao mesmo estado lógico.

Iceberg acrescenta essa descrição. A tabela é definida por metadados, não por “todos os arquivos que por acaso estão nesta pasta”. Isso também permite que um arquivo continue existindo fisicamente sem fazer parte do snapshot atual.

Caminho de uma leitura

flowchart TD
  C[Catalogo: tabela e metadado atual] --> M[Arquivo de metadados da tabela]
  M --> S[Snapshot escolhido]
  S --> L[Manifest list]
  L --> F[Manifests]
  F --> D[Arquivos de dados e de exclusao]

O arquivo de metadados descreve schemas, particionamento e snapshots. A manifest list resume os manifests de um snapshot. Os manifests descrevem arquivos e estatísticas. Essa hierarquia permite descartar partes da tabela antes de abrir todos os arquivos de dados. O leitor fixa o snapshot com o qual vai trabalhar. Referência: estrutura do formato.

Como uma escrita se torna visível

Um escritor prepara arquivos e novos metadados. A publicação troca a referência atual da tabela usando o mecanismo atômico do catálogo. O ponto de visibilidade é essa publicação, não o primeiro upload do lote.

Catalogo aponta para M10.
Escritor A prepara arquivos e M11, baseado em M10.
Escritor B publica M12 antes de A terminar.
A tenta publicar supondo que o atual ainda seja M10.
O catalogo detecta que a base mudou; A precisa revalidar o commit.

Esse é o princípio do controle otimista. Duas adições independentes podem ser conciliáveis; uma exclusão que depende de linhas modificadas por outro escritor pode exigir abortar e refazer trabalho. Retentar a publicação sem validar o conflito não preserva automaticamente a correção. Referência: concorrência e commits.

Curiosidade: time travel não exige copiar tudo

Snapshots podem compartilhar arquivos que não mudaram. Uma nova versão da tabela não precisa duplicar todos os Parquet: ela pode referenciar grande parte dos mesmos arquivos. O custo aparece nos arquivos novos, nas versões ainda retidas e nos metadados.

Isso explica por que apagar manualmente um Parquet “antigo” pode quebrar uma consulta histórica ou até uma versão atual que ainda o referencia.

Limites da atomicidade

A publicação descrita aqui é da tabela. Não se deve inferir uma transação única que atualiza arbitrariamente várias tabelas, envia Kafka e grava uma API externa. Isso depende de mecanismos adicionais do catálogo, motor ou aplicação.

Exemplo de falha: o upload termina e o commit falha. Os arquivos podem ficar órfãos: existem no armazenamento, mas nenhum snapshot publicado os usa. A limpeza segura desses objetos depende de prazo e conhecimento do estado da tabela.

Aprofundamento aplicado

Conflito de publicação e conflito de dados

Dois escritores podem preparar novos arquivos a partir do mesmo snapshot. Se ambos apenas acrescentam conjuntos independentes, o protocolo pode permitir reaplicar o commit sobre uma base mais nova. Se um escritor apaga dados selecionados por condição, precisa validar que mudanças concorrentes não invalidaram a decisão.

Portanto, retentar uma troca de ponteiro não basta para qualquer operação. O motor e o catálogo precisam implementar as validações necessárias; o formato não executa sozinho o protocolo. Referência: concorrência otimista.

Leitor fixa uma versão

Se uma consulta começou no snapshot S10, uma publicação S11 não exige que ela mude para S11 no meio da execução. Manter a referência consistente evita misturar arquivos de estados distintos, mas exige conservar os arquivos usados durante a leitura.

Exercício: desenhe dois appends concorrentes e depois um append concorrendo com uma exclusão por predicado. Resultado esperado: explicar quais fatos precisam ser revalidados em cada caso, sem tratar todo conflito como uma simples falha de rede.

Relacionado: 3. Iceberg - Time Travel, Deletes e Manutenção · 4. Iceberg no S3 e no R2 - Catálogos e Motores.

---

Parte de 0. MOC Apache Iceberg