Inspect the current partition spec with DESCRIBE EXTENDED or the catalog REST partitions endpoint to understand existing transforms
Add a new partition field using ALTER TABLE ... ADD PARTITION FIELD with a transform such as months(event_ts) or bucket(user_id, 128)
Verify that Iceberg records the new spec as a distinct partition spec version in the table metadata JSON rather than mutating the old one
Write new data; confirm that new files land in paths reflecting both old and new partition fields
Run a query spanning old and new partitions to confirm the query planner reads both spec versions without error
Known gotchas
Partition evolution is non-destructive by default: old files retain their original spec, so scans touching historical data must read both specs and may be less prunable until data is rewritten
Removing a partition field with DROP PARTITION FIELD does not delete data but prevents new writes from using that field; mixed-spec scans continue until a full rewrite
Hidden partition transforms (truncate, bucket, dates) are not visible in SQL predicates and must be inferred by the planner from column predicates; predicate pushdown only works when query filters match the transform input column
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp