Renames an existing column in a Delta table using column mapping. The physical column name in Parquet files remains unchanged.
ALTER TABLE <table> RENAME COLUMN [IF EXISTS] <old_name> TO <new_name>## Overview Renames an existing column by updating the logical-to-physical column mapping. The physical column name in the underlying Parquet files is not modified. This is a metadata-only operation. ## Behavior - The source column must exist in the current schema (unless IF EXISTS is specified). If the column is missing and IF EXISTS is not used, the command fails. - The target column name must not already exist in the schema. If a column with the new name is already present, the command fails with a duplicate column error. - Column mapping mode must be enabled (`delta.columnMapping.mode = 'name'`). Without column mapping, the logical column name is the same as the physical Parquet column name, and renaming is not possible. - The COLUMN keyword is optional. - A single metadata-only commit is written to the Delta log. - Nested struct fields can be renamed using dot-separated paths (e.g., `address.zip` TO `address.postal_code`). ## Compatibility Column renaming via column mapping is a standard Delta Lake feature. All Delta readers that support column mapping mode 'name' or 'id' will resolve the new logical name correctly.
| Name | Type | Description |
|---|---|---|
table | Fully qualified table name or registered table name. The table must be registered in the current session. | |
old_column_name | Current column name. | |
new_column_name | New column name. | |
if_exists | Don't error if column doesn't exist. |
-- Rename a column
ALTER TABLE warehouse.sales.users RENAME COLUMN user_name TO username;-- Rename with IF EXISTS guard
ALTER TABLE warehouse.sales.users RENAME COLUMN IF EXISTS old_col TO new_col;-- Rename a nested struct field
ALTER TABLE warehouse.sales.customers RENAME COLUMN address.zip TO address.postal_code;