Renaming a table

Using the tools rename subcommand, you can rename one or more tables at the same time, move a table to another directory within the same database, replace one table with another one within the same transaction.

General command format:

ydb [global options...] tools rename [options...]

View a description of the command to rename a table:

ydb tools rename --help

Subcommand parameters

A single run of the tools rename command executes a single rename transaction that may include one or more operations to rename different tables.

Parameter name Parameter description
--item <property>=<value>,... Description of the rename operation. Can be specified multiple times if multiple rename operations need to be executed within a single transaction.

Required properties:
  • source, src, and s: Path to the source table.
  • destination, dst, and d: Path to the destination table. If the destination path contains folders, they must be created in advance.
Advanced properties:
  • replace, force: Overwrite the destination table. If True, the destination table is overwritten with its data deleted. False: If the destination table exists, an error is returned and the entire rename transaction is canceled. Default value: False.
--timeout <value> Operation timeout, ms.

When including multiple rename operations in a single tools rename call, they're executed in the specified order, but within a single transaction. This lets you rotate the table under load without data loss: the first operation is renaming the working table to the backup one and the second is renaming the new table to the working one.

Examples

  • Renaming a single table:

    ydb tools rename --item src=old_name,dst=new_name

  • Renaming multiple tables within a single transaction:

    ydb tools rename \
  --item source=new-project/main_table,destination=new-project/episodes \
  --item source=new-project/second_table,destination=new-project/seasons \
  --item source=new-project/third_table,destination=new-project/series

  • Moving tables to a different directory:

    ydb tools rename \
  --item source=new-project/main_table,destination=cinema/main_table \
  --item source=new-project/second_table,destination=cinema/second_table \
  --item source=new-project/third_table,destination=cinema/third_table

  • Replacing a table

    ydb tools rename \
  --item replace=True,source=pre-prod-project/main_table,destination=prod-project/main_table

  • Rotating a table

    ydb tools rename \
  --item source=prod-project/main_table,destination=prod-project/main_table.backup \
  --item source=pre-prod-project/main_table,destination=prod-project/main_table
Previous
Copying tables
Next
Setting TTL parameters