ALTER TABLE ADD COLUMNS

Adds multiple columns to an existing Delta table in a single atomic operation.

Category: ddl

Syntax

ALTER TABLE <table> ADD COLUMNS (<col1> <type1> [NOT NULL] [COMMENT '<desc>'], ...)

Description

## Overview Adds multiple columns to an existing Delta table in one atomic metadata commit. All columns are appended at the end of the schema. Unlike ADD COLUMN (singular), this variant does not support FIRST or AFTER positioning. ## Behavior - Before execution, every column name is checked against the current schema. If any of the specified column names already exist, the entire operation fails without adding any columns. - All columns are added in the order specified, as a single commit to the Delta log. No data files are modified. - After successful addition, the schema observer is notified to keep the catalog in sync. - An empty column list (no columns between the parentheses) is rejected. ## Compatibility This command follows standard Delta Lake schema evolution semantics. All columns are added at the end of the schema. Older Parquet files that lack these columns will project NULL for the new fields during reads.

Parameters

Name	Type	Description
`table`		Fully qualified table name (zone.schema.table) or registered table name. The table must already be registered in the current session.
`columns`		Column definitions to add.

Examples

-- Add two columns at once
ALTER TABLE warehouse.sales.orders ADD COLUMNS (
  discount DECIMAL(10,2) COMMENT 'Applied discount',
  coupon_code STRING
);

-- Add columns with mixed nullability
ALTER TABLE warehouse.sales.customers ADD COLUMNS (
  loyalty_tier STRING NOT NULL COMMENT 'Gold, Silver, or Bronze',
  points_balance INT,
  enrolled_at TIMESTAMP
);

-- Add nested struct fields
ALTER TABLE warehouse.sales.customers ADD COLUMNS (
  address.state STRING,
  address.country STRING NOT NULL COMMENT 'ISO 3166-1 alpha-2'
);

Pitfalls

If any column name conflicts with an existing column, the entire batch fails. No partial additions occur.
Unlike ADD COLUMN (singular), this variant does not support FIRST or AFTER positioning. All columns are appended at the end.
Adding many NOT NULL columns at once to a table with existing data may cause read-time issues if there is no default value strategy in place.