Apache Iceberg V4 ganha chaves primárias, mas a maioria das regras começa sem enforcement

Em 27 de outubro de 2026, a comunidade Iceberg aprovou a adição de table constraints à especificação V4, com 8 votos +1 (5 deles vinculantes) e nenhum -1. São três tipos: check, unique e primary-key. As regras ficam nos metadados da tabela, separadas do schema, e apontam para as colunas pelo field ID. Renomear uma coluna, portanto, não quebra a constraint. A unique segue o padrão SQL para nulos (linha com nulo na chave não entra na comparação). A primary key exige valores distintos e nunca nulos, e só pode haver uma por tabela.

O ponto que mais confunde é o flag enforced. Ele é uma promessa sobre gravações futuras, não sobre o histórico: uma constraint pode estar enforced numa tabela que já contém violações. Quem diz se a regra vale para os dados de hoje é o constraint-statuses, registrado em cada snapshot, com quatro listas (validated, valid, invalid e unvalidated). Validated significa checagem completa. Valid significa que a regra vale por indução: o pai estava bom e as mudanças do commit foram checadas. Constraint ausente de todas as listas conta como unvalidated. Os status são imutáveis, então o time travel mostra o veredito da época. Uma validação posterior vira novo snapshot com a operação replace.

Há custos operacionais. Num retry de commit, as constraints enforced precisam valer contra o novo snapshot pai, e os status são recalculados. Em tabelas com muitos writers concorrentes, isso repete a checagem de unicidade a cada tentativa. A spec também não traz chaves estrangeiras, e proíbe float, double, geometry e geography em chaves unique e primary-key.

Para quem opera pipelines de migração de warehouse para Iceberg, a leitura é que a chave primária passa a ter lugar declarado, mas não vira garantia automática. Na prática, vale tratar o status do snapshot como a fonte de verdade e o enforced como política de escrita. Para planners e quem modela dados, só faz sentido confiar em uma chave (para remover um DISTINCT, por exemplo) quando o status for validated ou valid.