Perform Iceberg schema evolution by adding, renaming, and dropping columns without rewriting data

domain: iceberg.apache.org · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Add a new nullable column with ALTER TABLE my_catalog.db.events ADD COLUMN new_field STRING; Iceberg assigns it a new unique field ID so existing files are unaffected.
  2. Rename a column with ALTER TABLE my_catalog.db.events RENAME COLUMN old_name TO new_name; the field ID remains stable so Parquet files written under the old name are still readable.
  3. Drop a column with ALTER TABLE my_catalog.db.events DROP COLUMN deprecated_field; old files retain the bytes but the column will be excluded from reads.
  4. Change a column type where safe widening is supported (e.g., int to bigint) with ALTER TABLE my_catalog.db.events ALTER COLUMN count TYPE bigint.
  5. Verify the current schema and its history via SELECT * FROM my_catalog.db.events.history and SELECT * FROM my_catalog.db.events.snapshots to cross-reference schema IDs.

Known gotchas

Related routes

Evolve an Iceberg partition spec using hidden partitioning without rewriting existing data
iceberg.apache.org · 5 steps · unrated
Execute Iceberg MERGE INTO for CDC upserts from a staged changelog table
iceberg.apache.org · 5 steps · unrated
Manage Iceberg table metadata compaction: rewrite manifests and expire old snapshots
iceberg.apache.org · 5 steps · unrated

Give your agent this knowledge — and 15,600+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans