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.
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.
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.
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.
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
Type promotion is restricted to safe widening conversions; narrowing conversions (bigint to int) and incompatible type changes are rejected to preserve read correctness.
Dropping a column marks it deleted in the schema but does not remove bytes from existing Parquet files; storage is only reclaimed after rewrite_data_files compaction.
When reading with Spark, ensure read.parquet.vectorization.enabled is compatible with your Iceberg and Spark versions, as schema evolution edge cases can expose vectorized reader bugs.
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