ALTER TABLE ALTER COLUMN TYPE

Changes the data type of an existing column via type widening. Requires the delta.enableTypeWidening table property.

Category: ddl

Syntax

ALTER TABLE <table> ALTER COLUMN <column> TYPE <new_type>

Description

## Overview Changes the data type of an existing column to a wider type. Type widening is a Delta Lake feature that allows safe schema evolution without rewriting data files. The Delta reader automatically casts values from older Parquet files (which contain the narrower type) to the new wider type at read time. ## Allowed Type Widenings | From | To | |------|----| | BYTE (TINYINT) | SHORT, INT, BIGINT | | SHORT (SMALLINT) | INT, BIGINT | | INT (INTEGER) | BIGINT | | FLOAT | DOUBLE | | DATE | TIMESTAMP | | DECIMAL(p1,s1) | DECIMAL(p2,s2) where p2 >= p1 and s2 >= s1 | | DECIMAL128 | DECIMAL256 (with p2 >= p1, s2 >= s1) | Narrowing conversions (e.g., BIGINT to INT) and unrelated type changes (e.g., STRING to INT) are rejected. ## Behavior - The table property `delta.enableTypeWidening` must be set to `'true'` before executing this command. If the property is not set, the ALTER TABLE builder will return an error. - The column must exist in the table schema. If the column is not found, the command fails. - The operation records a `delta.typeChanges` metadata entry on the column, noting the original type, new type, and table version. This metadata enables the reader to cast values from older files. - After a successful type change, the table is re-registered with the DataFusion session so that subsequent queries see the updated schema immediately. - No data files are rewritten. Reads perform on-the-fly casting from the narrower physical type to the wider logical type. ## Protocol Requirements Type widening requires: - Writer version 7 with the `typeWidening` (or `typeWidening-preview`) feature. - Reader version 3 with the `typeWidening` (or `typeWidening-preview`) feature. These protocol versions are automatically upgraded when `delta.enableTypeWidening` is set. ## Compatibility Type widening is compatible with Iceberg UniForm for all widenings except DATE to TIMESTAMP. When IcebergCompatV2 is enabled, DATE to TIMESTAMP widening is rejected.

Parameters

Name	Type	Description
`table`		Fully qualified table name or registered table name. The table must be registered and must have the delta.enableTypeWidening property set to true.
`column_name`		Column to alter.
`new_type`		The target data type. Must be a valid widening of the column's current type. See the allowed widening paths below.

Examples

-- Widen an integer column to bigint
ALTER TABLE warehouse.sales.products ALTER COLUMN quantity TYPE BIGINT;

-- Widen a float column to double
ALTER TABLE warehouse.sales.measurements ALTER COLUMN temperature TYPE DOUBLE;

-- Widen decimal precision
ALTER TABLE warehouse.sales.orders ALTER COLUMN amount TYPE DECIMAL(15,4);

-- Enable type widening first, then widen
ALTER TABLE warehouse.sales.events SET TBLPROPERTIES ('delta.enableTypeWidening' = 'true');
ALTER TABLE warehouse.sales.events ALTER COLUMN event_id TYPE BIGINT;

Pitfalls

Forgetting to set delta.enableTypeWidening before running this command causes a protocol error. Always enable the property first.
DATE to TIMESTAMP widening is not compatible with Iceberg UniForm. If your table uses IcebergCompatV2, this widening is rejected.
Type widening metadata (delta.typeChanges) is cumulative. Each widening adds an entry. Manually editing or removing this metadata can break reads of older files.