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:

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

Renaming tables - 图1

View a description of the command to rename a table:

  1. ydb tools rename --help

Renaming tables - 图2

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 nameParameter 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:

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

    Renaming tables - 图3

  • Renaming multiple tables within a single transaction:

    1. ydb tools rename \
    2.   --item source=new-project/main_table,destination=new-project/episodes \
    3.   --item source=new-project/second_table,destination=new-project/seasons \
    4.   --item source=new-project/third_table,destination=new-project/series

    Renaming tables - 图4

  • Moving tables to a different directory:

    1. ydb tools rename \
    2.   --item source=new-project/main_table,destination=cinema/main_table \
    3.   --item source=new-project/second_table,destination=cinema/second_table \
    4.   --item source=new-project/third_table,destination=cinema/third_table

    Renaming tables - 图5

  • Replacing a table

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

    Renaming tables - 图6

  • Rotating a table

    1. ydb tools rename \
    2.   --item source=prod-project/main_table,destination=prod-project/main_table.backup \
    3.   --item source=pre-prod-project/main_table,destination=prod-project/main_table

    Renaming tables - 图7