Iceberg - Schema e Particionamento Oculto

Schema é mais que uma lista de nomes

Iceberg associa identificadores aos campos. Renomear uma coluna mantendo sua identidade é diferente de apagar a coluna e criar outra com o mesmo nome. O leitor usa os metadados da tabela para interpretar a evolução, em vez de adivinhar somente pela posição ou nome encontrados em cada arquivo.

Schema inicial: campo 17 = preco
Depois do rename: campo 17 = valor
Depois de excluir e recriar: um novo campo recebe outro identificador

A última operação não significa que a nova coluna herda automaticamente os valores históricos da antiga. Compatibilidade também restringe mudanças de tipo: ampliar um tipo compatível é diferente de converter arbitrariamente texto em número. Referência: evolução de schema.

Particionamento oculto

No particionamento tradicional por pastas, a aplicação frequentemente precisa manter uma coluna derivada, como dia, coerente com instante. Em Iceberg, a especificação de particionamento pode aplicar uma transformação ao campo original.

Exemplos: agrupar um timestamp por dia ou mês; distribuir uma chave em buckets; truncar um valor conforme uma regra. A consulta continua filtrando o campo de domínio. O planejador usa a transformação para localizar as partições relevantes. Referência: hidden partitioning.

Exemplo SQL, com dialeto identificado

O exemplo abaixo usa Spark SQL com catálogo Iceberg configurado como lake. O namespace lake.vendas precisa existir. Não é sintaxe universal para todos os motores.

CREATE TABLE lake.vendas.eventos (
    pedido_id BIGINT,
    instante TIMESTAMP,
    valor DECIMAL(12, 2)
)
USING iceberg
PARTITIONED BY (days(instante));

SELECT SUM(valor)
FROM lake.vendas.eventos
WHERE instante >= TIMESTAMP '2026-09-01 00:00:00'
  AND instante <  TIMESTAMP '2026-09-02 00:00:00';

A consulta expressa o intervalo desejado. Não precisa repetir uma condição manual sobre uma coluna de partição. O filtro exato continua necessário: descartar arquivos é uma otimização, não substitui avaliar a condição nas linhas restantes.

Evoluir a partição

Uma tabela pode mudar de particionamento diário para mensal. Arquivos existentes continuam associados à especificação com que foram escritos; novas escritas podem usar outra. Metadados permitem interpretar essa coexistência.

Isso não reorganiza retroativamente todos os arquivos. Para mudar a disposição física do histórico, pode ser necessário reescrevê-lo. Alterar metadados e redistribuir terabytes de dados têm custos muito diferentes.

Curiosidade: granularidade demais também custa

Particionar por um identificador quase único pode produzir muitas partições e arquivos pequenos. Cada arquivo acrescenta metadados, aberturas e requisições. Já uma partição muito ampla pode reduzir a capacidade de descartar dados.

A escolha precisa refletir filtros e volume: “mais partições” não implica “mais rápido”. Uma boa ordenação dentro dos arquivos também pode ajudar as estatísticas a eliminar blocos, mesmo sem multiplicar partições.

Aprofundamento aplicado

Renomear preserva identidade; recriar muda o campo

Ao planejar evolução, registre campo, ID, tipo e significado. Renomear valor para valor_bruto preservando identidade não converte os valores antigos nem muda sua unidade. Uma alteração de centavos para reais exige transformação dos dados ou modelagem explícita, mesmo que ambos caibam em um tipo numérico compatível. Referência: evolução de schema.

Partições antigas continuam existindo

Após mudar de mês para dia, arquivos antigos seguem a especificação anterior. O planejamento considera a especificação de cada arquivo. Uma consulta não pode assumir que todo o histórico já foi reorganizado pelo novo esquema.

Cenário: o último mês recebe muitas consultas por hora, enquanto anos antigos são lidos raramente. Reescrever somente dados recentes pode ter relação de custo melhor que reorganizar todo o histórico, dependendo da carga e do motor.

Exercício: desenhe dois arquivos sob partição mensal e dois sob diária. Resultado esperado: explique como um filtro de data pode selecionar candidatos nos dois layouts e por que o filtro exato ainda precisa ser aplicado aos registros.

Relacionado: 1. Iceberg por Dentro - Metadados, Snapshots e Commits · 3. Parquet e S3 com DuckDB.

---

Parte de 0. MOC Apache Iceberg