Short answer: Iceberg does nested-schema evolution by stable field ID, not by column position or path. That means you can add, drop, rename, reorder, and in many cases promote types for fields inside structs without rewriting files. But metadata-only changes are only safe if every reader you use understands and honors Iceberg field IDs and the format version rules you rely on.
Field IDs are numeric tokens attached to schema fields in the Iceberg table metadata. For nested data the ID is assigned to each field inside a struct or list element. When a reader resolves on-disk files, it matches requested fields to physical data using those IDs, not by name or by position. That prevents common accidental mismatches when you rename or reorder fields.
This ID model is described in the Iceberg evolution and spec documentation, which explains how field IDs, type descriptors, and schema branches are recorded. Verify the behavior for the table format version you use because type-promotion rules and some evolution semantics changed between Iceberg v1, v2, and v3. (Facts checked October 27, 2026.)
These are the practical rules you must check before making a metadata-only schema change that touches nested fields.
These rules come from the Iceberg evolution documentation and the formal spec. When in doubt, run compatibility assertions that exercise your readers, as I show in the worked examples. Also read the API docs for how to set field IDs and defaults programmatically.
At read time Iceberg uses the table schema and file-level schema together with field IDs to build a column projection and a resolver. The resolver maps requested columns to file columns by ID, then applies on-the-fly conversions or defaulting if the table schema differs. If the reader does not implement ID-based resolution, it may fall back to name-based or position-based resolution, which can misread nested structs.
Resolution can do these things: inject default values for missing fields when a default is supplied, convert supported primitive types (within the allowed promotion rules for your format version), and ignore unknown fields present in files. Where the reader cannot reconcile the type or missing required values, it raises an error or returns nulls depending on engine behavior.
The SQL and API surface differs by engine. Below are Spark DDL examples and the programmatic checks I use when operating Iceberg tables. These examples assume you created a table with nested_struct of type struct<a:int,b:struct<c:string>>. Adjust identifiers and cluster endpoints for your environment.
<!-- wp:code -->
CREATE TABLE db.nested_example (
id bigint,
nested struct<a:int,b:struct<c:string>>
) USING ICEBERG;
<!-- /wp:code -->This DDL uses the Spark DDL layer documented in the Iceberg Spark DDL guide. Spark will assign IDs when creating the table unless you explicitly set them via the API. If you require specific IDs to coordinate cross-engine clients, use the Iceberg API to write schema objects with explicit IDs.
<!-- wp:code -->
ALTER TABLE db.nested_example ADD COLUMN nested.b.d int;
<!-- /wp:code -->When run in a Spark environment that speaks Iceberg DDL, this issues a metadata-only schema change that adds nested.b.d with a new field ID. Verify that the generated table metadata under the table location shows the new field with an ID. If you need to control the ID explicitly, use the Iceberg API documented in the API reference to build the Schema object and write the new metadata snapshot.
<!-- wp:code -->
ALTER TABLE db.nested_example RENAME COLUMN nested.b.c TO nested.b.c_name;
<!-- /wp:code -->This change keeps the same field ID. Engines that implement ID-based resolution will see the new name but map data by ID. Confirm by querying old files; they still return values for nested.b.c_name because the ID maps to the underlying data.
<!-- wp:code -->
-- This will not be a safe metadata-only change in most engines
ALTER TABLE db.map_example ALTER COLUMN mymap.key TYPE bigint;
<!-- /wp:code -->Map keys cannot be evolved in place. The Iceberg docs explicitly caution against in-place map-key modifications. In practice this means you must rewrite the column or create a new column with the new map type and migrate data. Do not assume metadata-only operations will work for map keys.
I build a pre-flight checklist that runs two kinds of assertions. First, a metadata sanity check that inspects table JSON metadata to ensure every modified field has an explicit new field ID and that no conflicting ID reuse exists. Second, a runtime compatibility matrix that reads files with each engine used in production to verify the read schema matches expectations.
Use the Iceberg table metadata JSON found under the table location. Programmatically check:
Tools: any language that reads JSON. The Iceberg API can produce the Schema object programmatically; see the API docs for the exact calls. These checks ensure the metadata change itself is well formed before we exercise readers.
Test read behavior on every engine version you run. My matrix looks like this in practice:
Include both the cluster or environment and the exact connector or runtime version, because behavior can differ. For Dremio-specific operational guidance and metadata table querying, read the Dremio blog post about Iceberg metadata tables and the resource guide for Iceberg on Dremio. The former explains how to inspect metadata snapshots using Dremio queries, which is useful during your matrix run. The latter collects practical configuration and connector notes helpful during rollout.
<!-- wp:code -->
-- Example smoke test SQL run on each engine
SELECT id, nested.b.c_name, nested.b.d
FROM db.nested_example
LIMIT 10;
<!-- /wp:code -->Make sure the query returns expected non-null values for pre-existing rows and that newly added fields either return null or the default you set.
Rolling a schema change to multiple engines is where things go wrong. I use a gate that requires explicit green tests from every reader and a staged promotion across clusters. Here is the checklist I run before changing production metadata.
Staging and per-engine verification is essential. Dremio provides guides for integrating Iceberg and explains v2 versus v3 differences, which is helpful when you decide whether to rely on newer format-version promotions or to perform a rewrite. Read the Dremio post comparing Iceberg v2 and v3 to help choose your target format version before doing schema-changing operations.
Here are the failure modes I have operated into, and the recovery actions that worked.
Keep automated rollback snapshots and a short retention period to make metadata rollbacks practical. The Iceberg metadata tables and the Dremio metadata introspection guide explain how to find the snapshot IDs you need to roll back.
Measure these indicators for at least one traffic cycle or the lifetime of slow changes like backfills.
These metrics capture both correctness and operational cost. For example, a sudden spike in read latency after a metadata change often signals an engine falling back to unsafe resolution and re-reading or re-processing data. If you operate Dremio, the resource guide linked earlier contains practical operational hints to measure and analyze these effects in Dremio deployments.
Here is a concrete matrix I ran when adding nested.b.d to a production table used by batch Spark and interactive Dremio.
Results: Spark and Dremio returned the expected rows for existing nested fields and null for newly added nested.b.d. Trino failed to map the nested rename correctly in the older connector version and returned nulls for existing values. Conclusion: delay the production change until Trino connector was upgraded, or rewrite files and introduce a new column path that Trino could resolve reliably.
That example shows why per-engine gating is non-negotiable. Use the operator-visible region and cluster labels like the DML validation cluster and the incremental-read validation cluster in your test plans so that engineers can map results back to running deployments and connector versions.
If a reader cannot support the metadata-only change, you have three options.
Which option you pick depends on service-level requirements, the ability to upgrade clients, and the cost of rewrites. The Iceberg spec and evolution docs explain when a rewrite is conceptually necessary. If the docs are ambiguous for your engine combination, run the matrix tests or prefer the conservative option of a rewrite.
My recommended workflow for nested-schema evolution, distilled into steps you can operationalize.
This workflow balances low-cost metadata evolution with the practical reality that not every client is equal. The Dremio resource guide for Iceberg is a convenient reference for configuring Dremio-specific connectors and understanding how Dremio surfaces metadata tables for inspection during these steps.
Start here if you want to validate a nested struct change under real-world conditions, across Spark and a SQL engine that uses Iceberg readers. The goal is to exercise metadata-only changes, detect engines that ignore field IDs, and confirm read-time resolution behaves as documented. This is a hands-on script you can run in a staging environment.
Assumptions, checked on October 27, 2026: your Iceberg distribution supports schema evolution APIs described in the Apache Iceberg documentation and your engines are at versions for which you have verified behavior. If you need to confirm exact behavior, check the Iceberg documentation and your engine release notes before running the test.
Use both a Spark session and a second engine. Replace engine commands with your environment specifics. Run each step and record results in a short test log.
-- Step 0, create base table with nested struct
CREATE TABLE db.orders (
order_id BIGINT,
customer STRUCT>
)
USING iceberg;
-- Insert a few rows with address populated
INSERT INTO db.orders VALUES
(1, NAMED_STRUCT('id', 10, 'name', 'Alice', 'address', NAMED_STRUCT('street', '1 Main', 'city', 'Metropolis'))),
(2, NAMED_STRUCT('id', 11, 'name', 'Bob', 'address', NAMED_STRUCT('street', '2 Side', 'city', 'Gotham')));
Note, the SQL syntax above is an example DDL for engines that accept Iceberg Spark DDL. For other engines use the documented DDL form. The important outcome is a table with stable field IDs assigned by Iceberg metadata. Record the table schema with the Iceberg API or catalog to capture those IDs before making changes.
-- Step 1, metadata-only add: introduce a nested "phone" field under customer.address
ALTER TABLE db.orders
ADD COLUMN customer.address.phone STRING;
-- Write a new row that includes phone
INSERT INTO db.orders VALUES
(3, NAMED_STRUCT('id', 12, 'name', 'Carla', 'address', NAMED_STRUCT('street', '3 Circle', 'city', 'Star', 'phone', '555-0103')));
For this change to be metadata-only Iceberg needs to add a new field entry with a new field ID inside the nested address struct. Confirm the change by reading the Iceberg schema via the catalog API or by SHOW CREATE TABLE if supported. Record the field ID for customer.address.phone.
-- Step 2, validation queries
-- A: Read all rows in Spark and project the new field
SELECT order_id, customer.address.street, customer.address.city, customer.address.phone FROM db.orders ORDER BY order_id;
-- B: Read same projection in the other engine and compare outputs
-- Export query results to CSV from both engines and run a diff line by line
Expected behavior: rows 1 and 2 show null for phone, row 3 shows "555-0103". If the other engine shows the phone only for row 3 as well, that engine respects Iceberg field IDs. If it shows phone as null for all rows or fails, it may be name-matching only or using stale metadata.
-- Step 3, metadata-only rename: rename customer.name to customer.display_name using the Iceberg schema API
-- Use your engine or the Iceberg Java API to rename while preserving field ID.
-- Example using Iceberg SQL aliasing if available:
ALTER TABLE db.orders RENAME COLUMN customer.name TO customer.display_name;
After renaming, query both engines selecting the new name and the old name to detect difference. Some engines will allow selecting the old name for backwards compatibility, others will return an error. The key check is that the renamed column returns the original values, without rewriting files.
-- Step 4, verify post-rename reads
SELECT order_id, customer.display_name FROM db.orders ORDER BY order_id;
-- Attempt to read using the old name in each engine to see how they handle projection
SELECT order_id, customer.name FROM db.orders ORDER BY order_id;
If an engine still returns values when selecting customer.name, it is performing a name alias or compatibility convenience. If it errors, your client queries need updating. If customer.display_name returns original names with no file rewrite, the ID-based rename worked.
Now test an unsafe change to confirm you must rewrite data. For example, map key types cannot be evolved in place. Also, changing a nested map into a struct is not metadata-only. These are important safety guards.
-- Step 5, unsafe change: replace map with struct or change map key type
-- First create a table with a nested map
CREATE TABLE db.prefs (
user_id BIGINT,
preferences MAP
)
USING iceberg;
INSERT INTO db.prefs VALUES
(1, MAP('theme', 'dark'));
-- Attempt a metadata-only change that changes the key type
ALTER TABLE db.prefs REPLACE COLUMNS (preferences MAP);
Expected behavior: Iceberg schema evolution semantics disallow in-place map key type changes. Your engine should reject the ALTER or it will accept but break readers. Record the exact error message. If the ALTER succeeds without rewriting data, you have a serious compatibility risk: different readers may interpret keys differently. To fix this you must rewrite files after the schema change or create a new table and migrate data with a controlled write job.
Automating schema checks prevents accidental incompatible changes. The CI gate described here integrates with your schema registry or deployment pipeline. It uses schema compatibility assertions that compare the current table schema and proposed change, and it will reject changes that are unsafe without a data rewrite.
When an assertion fails, the CI gate should block the change and produce actionable remediation steps. For example, the failure message for a map key change should recommend creating a new table and streaming a rewrite job that performs explicit key conversion.
# Pseudocode for a CI step that validates a proposed schema change
# 1. Load current Iceberg schema via catalog API
current = iceberg.loadTable('db.orders').schema()
# 2. Load proposed schema from change request
proposed = parse_proposed_schema('proposed_schema.sql')
# 3. For each changed field, check compatibility
for change in diff(current, proposed):
if change.type == 'rename' and change.is_nested:
assert change.old_field_id == change.new_field_id, 'Rename must preserve field ID'
if change.type == 'map_key_type_change':
fail('Map key type change requires data rewrite and is not allowed by CI gate')
if change.type == 'type_promotion':
# check allowed promotions based on format version
assert allowed_promotion(current.format_version, change)
Implement this as a small service or a pipeline stage. Use the Iceberg API to obtain precise field IDs and type metadata. If you cannot access field IDs from a wrapped catalog, add a step that fetches the table metadata file directly and parses the schema to avoid mismatches introduced by catalog abstractions.
Add the assertion step as a required status check before merging schema changes. If a change requires a rewrite, the CI should output a job spec for the necessary rewrite, including estimated scan size and a suggested write parallelism. This keeps schema changes explicit and auditable.
You already have a smoke-test matrix example. Here is a compact decision table that maps observed outcomes to operator actions. Use it during rollout, after any metadata-only schema change, and as part of nightly checks.
Use the table below to decide the next action after a schema change. Capture the engine name, version, and the exact query used to produce the observation.
For each case record the remediation steps and the time-to-resolution target. Typical targets: 1 hour for blocking rollbacks in staging, 24 hours for controlled migrations with a defined job runbook.
Some engines provide compatibility modes or configuration flags that change read-time behavior. Document those flags in your matrix. Do not assume flags exist across projects. If you rely on a vendor-provided connector, confirm the connector version and test it explicitly. When in doubt, require a file rewrite as the safe path, especially for customer-facing read services.
After applying a nested-schema change, measuring the right signals lets you detect silent compatibility issues and performance regressions. Concentrate on read correctness, failure rates, query latencies, and write plumbing.
Set alerts that trigger investigation rather than immediate rollbacks. Suggested thresholds:
Keep a small set of canary queries that project the exact nested fields changed. Run them constantly against each engine and compare results. Automate diffs and fail the deployment pipeline if comparisons diverge beyond a small epsilon.
# Pseudocode for a monitoring check that compares two engines
# 1. Periodically run the same projection on both engines
spark_rows = run_query(spark, "SELECT order_id, customer.address.phone FROM db.orders WHERE order_id IN (1,2,3)")
other_rows = run_query(other, "SELECT order_id, customer.address.phone FROM db.orders WHERE order_id IN (1,2,3)")
# 2. Compare results
if diff(spark_rows, other_rows) > allowed_tolerance:
emit_alert('Nested field projection mismatch')
Log exact schema snapshots alongside the query results. When investigating a mismatch you want the Iceberg table schema JSON, the client-side resolved schema, and the query plan from each engine. These three artifacts usually reveal whether the problem is metadata propagation, reader mismatch, or a genuine data issue.
A1: Yes if every engine you use honors Iceberg field IDs. Some older connectors or misconfigured clients may fall back to name or position resolution and misread data. Validate in your runtime matrix.
A2: No. Map keys cannot be evolved in place. You must rewrite data or create a new column and migrate. This is a documented technical caution in the Iceberg evolution guidance.
A3: The Iceberg spec and evolution docs specify allowed promotions and conversions, and those rules changed between format versions. Check the spec and your table's format version. If behavior is unclear, run engine-level tests. (Facts checked October 27, 2026.)
A4: Track query errors per engine, null rates for new fields on old rows, read latencies, scan sizes, rewrite throughput if you ran a migration, and snapshot churn. These show both correctness and cost.
A5: Table metadata JSON appears under the table location and in Iceberg metadata tables. If you run Dremio, the Dremio blog post on Iceberg metadata tables explains how to query and inspect snapshots using Dremio, which is handy for snapshot IDs and schema history.
A6: Use a staged snapshot in a staging environment. Run your runtime compatibility matrix across every cluster and connector version, including instances like the DML validation cluster and the incremental-read validation cluster. Only promote once every reader passes the smoke tests.
These guides cover adjacent implementation details that are outside this article's main scope.
For a deeper treatment, download Apache Iceberg: The Definitive Guide, co-authored by Alex Merced and available free from Dremio.
To put the catalog and table-format ideas into practice, explore Dremio's Apache Iceberg platform.
Deploy agentic analytics directly on Apache Iceberg data with no pipelines and no added overhead.
Editor’s note, September 2026. This post was published in September 2023 and some product details have changed since. Nessie is still available and self-deployable under the Apache-2.0 licence, and it remains the clearest implementation of catalog-level branching. It is not an Apache Software Foundation project, and its development has slowed considerably. For how the current […]
Iceberg keeps per-file bounds automatically but table-level NDV statistics only when you compute them. Why that decides join order, and how to keep them fresh.
With its capabilities in on-prem to cloud migration, data warehouse offload, data virtualization, upgrading data lakes and lakehouses, and building customer-facing analytics applications, Dremio provides the tools and functionalities to streamline operations and unlock the full potential of data assets.