.rename table command

Changes the name of an existing table.

The .rename tables command changes the name of a number of tables in the database as a single transaction.

Permissions

You must have at least Table Admin permissions to run this command.

Syntax

.rename table OldName to NewName

.rename tables NewName = OldName [ifexists] [, ...]

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
OldName	string	✔️	The name of an existing table. An error is raised and the whole command fails if OldName doesn't name an existing table, unless ifexists is specified.
NewName	string	✔️	The new name for the table that used to be called OldName.
ifexists	string		If specified, the command will handle the scenario where the table doesn't exist. Instead of failing, it will proceed without attempting to rename the table that doesn't exist.

Remarks

This command operates on tables of the database in scope only. Table names can't be qualified with cluster or database names.

This command doesn't create new tables, nor does it remove existing tables. The transformation described by the command must be such that the number of tables in the database doesn't change.

The command does support swapping table names, or more complex permutations, as long as they adhere to the rules above. For example, ingest data into multiple staging tables, and then swap them with existing tables in a single transaction.

Examples

Imagine a database with the following tables: A, B, C, and A_TEMP. The following command will swap A and A_TEMP (so that the A_TEMP table will now be called A, and the other way around), rename B to NEWB, and keep C as-is.

.rename tables A=A_TEMP, NEWB=B, A_TEMP=A

The following sequence of commands:

1. Creates a new temporary table
2. Replaces an existing or nonexisting table with the new table

// Drop the temporary table if it exists
.drop table TempTable ifexists

// Create a new table
.set TempTable <| ...

// Swap the two tables
.rename tables TempTable=Table ifexists, Table=TempTable

// Drop the temporary table (which used to be Table) if it exists
.drop table TempTable ifexists

Rename source table of a materialized view

If the table being renamed is the source table of a materialized view, you can specify the following property as part of the .rename command:

.rename table OldName to NewName with (updateMaterializedViews=true)

The table will be renamed and all materialized views referencing OldName will be updated to point to NewName, in a transactional way.