ALTER TABLE ADD COLUMN

Adds a single column to an existing Delta table's schema.

Category: ddl

Syntax

ALTER TABLE <table> ADD COLUMN <name> <type> [NOT NULL] [COMMENT '<desc>'] [FIRST | AFTER <col>]

Description

## Overview Adds a new column to an existing Delta table. The operation writes a new metadata-only commit to the Delta log without rewriting any data files. Existing Parquet files are not modified; readers fill in NULL (or the default value) for the new column when reading older files. ## Behavior - The table must be registered in the current session. If the table is not found, the command returns an error suggesting CREATE DELTA TABLE or OPEN DELTA TABLE. - If a column with the same name already exists, the command fails with a duplicate column error. - By default the new column is appended at the end of the schema. Use FIRST or AFTER to control placement. Column positioning is a metadata-only operation and does not require data file rewrites. - The COLUMN keyword after ADD is optional. Both `ADD COLUMN name TYPE` and `ADD name TYPE` are accepted. - After the column is added, the schema observer is notified so the catalog stays in sync. ## Compatibility ALTER TABLE ADD COLUMN follows standard Delta Lake schema evolution semantics. The operation is compatible with all Delta readers because new columns are simply absent from older Parquet files and are projected as NULL.

Parameters

Name	Type	Description
`table`		Fully qualified table name (zone.schema.table) or registered table name. The table must already be registered via CREATE DELTA TABLE or OPEN DELTA TABLE.
`column_name`		Column name to add.
`data_type`		Data type.
`nullable`		Whether the column allows NULLs.
`comment`		Column description.
`position`		FIRST or AFTER column_name.

Examples

-- Add a nullable string column at the end of the schema
ALTER TABLE warehouse.sales.orders ADD COLUMN notes STRING;

-- Add a non-nullable integer column with a comment
ALTER TABLE warehouse.sales.orders ADD COLUMN priority INT NOT NULL COMMENT 'Order priority (1-5)';

-- Add a column at the beginning of the schema
ALTER TABLE warehouse.sales.orders ADD COLUMN order_ref STRING FIRST;

-- Add a column after a specific existing column
ALTER TABLE warehouse.sales.orders ADD COLUMN discount DECIMAL(10,2) AFTER subtotal;

-- Add a nested struct field
ALTER TABLE warehouse.sales.customers ADD COLUMN address.zip_code STRING;

Pitfalls

Adding a NOT NULL column to a table that already contains data will prevent future reads from returning NULL for existing rows, which may cause errors if no DEFAULT is defined.
Column positioning (FIRST / AFTER) is metadata-only. Query tools that read Parquet column order directly, rather than consulting the Delta schema, may not reflect the new position.
Nested field additions (e.g., address.zip_code) require that the parent struct column already exists.