ALTER TABLE RENAME TO

Renames a table in the catalog and DataFusion session without modifying underlying Delta files.

Category: ddl

Syntax

ALTER TABLE <old_name> RENAME TO <new_name>

Description

## Overview Renames a table by updating the session registry and catalog. The underlying Delta files on storage are not moved, modified, or renamed. The table path (LOCATION) remains the same; only the logical name by which the table is referenced in SQL changes. ## Behavior - The old table name must be registered in the current session. If it is not found, the command fails. - The new table name must not already be in use. If a table with the new name exists, the command fails with a duplicate name error. - The operation deregisters the old name from the DataFusion session and registers the new name pointing to the same storage path. - This is a session-level operation. The catalog entry (if 3-part qualified) is updated as part of the rename. - No Delta log commits are written. The Delta table at the storage path is completely unaware of the rename. ## Compatibility Table renaming is a session and catalog operation, not a Delta protocol operation. Any Delta reader can continue to access the table at its storage path regardless of the name change.

Parameters

Name	Type	Description
`old_name`		Current fully qualified table name or registered table name. The table must be registered in the current session.
`new_name`		New name for the table. Must not conflict with any existing registered table name.

Examples

-- Rename a table
ALTER TABLE staging_orders RENAME TO orders;

-- Rename a fully qualified table
ALTER TABLE warehouse.staging.raw_events RENAME TO warehouse.staging.events;

-- Rename during a migration
ALTER TABLE warehouse.sales.customers_v1 RENAME TO warehouse.sales.customers_legacy;

Pitfalls

Views, pipelines, and other SQL objects that reference the old table name are not automatically updated. They will fail until manually updated to use the new name.
The rename does not persist across sessions unless the table is registered in the catalog with a 3-part qualified name.
The underlying storage path is unchanged. If you need to move data to a new location, use CLONE instead.