Type Promotion

Type promotion is a schema change that widens a column’s data type — for example, from a 32-bit integer to a 64-bit integer — in a way that every existing value can still be read as the new type. In table formats such as Apache Iceberg, a promotion is a metadata change: data files written with the old type are not rewritten, and readers convert their values to the new type as they read. Delta Lake calls the same capability type widening.

Why only widening is allowed

Because old files are never rewritten, a type change is only safe if every value that could exist in an old file has an exact equivalent in the new type. That holds when the new type contains the old one.

• Widening such as int to long is safe: every 32-bit integer is also a 64-bit integer.
• Narrowing such as long to int is not: old files may hold values that do not fit, and the reader would have to fail or silently change them.
• Changing kind such as int to string is not a promotion either. The conversion is possible, but other metadata computed from the old values — statistics, partition values — no longer means the same thing.

What Iceberg allows

The Iceberg specification lists the valid primitive promotions explicitly:

The list is short on purpose, and two details in the specification show why promotions have to be designed rather than assumed.

Old statistics keep their old encoding. Manifests store each file’s lower and upper bounds for a column without recording the type, and a promotion does not rewrite them. After float becomes double, older files’ bounds are still 4 bytes rather than 8, and the specification tells readers to infer the original type from the length. Promotion is only safe because this inference rule exists.

Partitioning can block a promotion. A promotion is not allowed on a column used as the source of a partition field if the partition transform would produce a different value after the change. The specification’s example is the bucket transform: it hashes 34 and 34L to the same bucket, so an int bucket source can become long, but "34" as a string hashes differently. Among the valid promotions, the specification names date to timestamp as the case where this restriction can apply, so a date column used for partitioning may not be promotable.

What Delta allows

Delta Lake’s type widening covers a somewhat broader set: integer widening from byte through short and int to long, float to double, byte, short, or int to double, date to timestamp without time zone, and several decimal widenings, including integer types to decimals with enough precision. It is a table feature that must be enabled, requires a newer protocol version that readers must support, and records each column’s type change history in the schema metadata. When a Delta table has its Iceberg compatibility feature enabled, the protocol requires every type change to be one that Iceberg’s format version 2 supports.

When the change you need is not a promotion

Some common schema changes fall outside these lists: an identifier that needs to become a string, a decimal that must hold fewer digits, a timestamp that needs a time zone. The options are then the ordinary ones — add a new column with the new type and backfill it, or rewrite the table — and both are real work with a migration period for consumers.

Two practical cautions apply even to allowed promotions. Every engine that reads the table must support the promotion, or the table becomes unreadable to it. And a promotion that is free for the table can still be a breaking change for someone downstream: a report, an export, or a service that expected 32-bit values. The general compatibility rules are covered in schema evolution and compatibility, and how columns are matched across schema versions in the first place is covered by field IDs. What schema changes cost underneath a lakehouse table is worked through in Storage, Compute, and Metadata: What Each Layer Actually Owns.

References: Apache Iceberg Table Spec, Schema Evolution; Delta Transaction Log Protocol, Type Widening.