translation

Перевод для https://st.yandex-team.ru/

Локально собралось без ошибок.

3 files changed, 72 insertions, 22 deletions

diff --git a/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md b/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md
index acf6d3c9153..8efda892283 100644
--- a/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md
+++ b/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md
@@ -19,13 +19,13 @@ The [`table index add` command](../../reference/ydb-cli/commands/secondary_index
 Since an index contains its own data derived from table data, when creating an index on an existing table with data, an operation is performed to initially build an index. This may take a long time. This operation is executed in the background and you can keep working with the table while it's in progress. However, you can't use the new index until it's created.
 
 An index can only be used in the order of the fields included in it. If an index contains two fields, such as `a` and `b`, you can effectively use it for queries such as:
-* `WHERE a = $var1 AND b = $var2`;
-* `WHERE a = $var1`;
+* `WHERE a = $var1 AND b = $var2`.
+* `WHERE a = $var1`.
 * `WHERE a > $var1` and other comparison operators.
 * `WHERE a = $var1 AND b > $var2` and any other comparison operators in which the first field must be checked for equality.
 
 This index can't be used in the following queries:
-* `WHERE b = $var1`;
+* `WHERE b = $var1`.
 * `WHERE a > $var1 AND b > $var2`, which is equivalent to `WHERE a > $var1` in terms of applying the index.
 * `WHERE b > $var1`.
 
@@ -82,6 +82,12 @@ FROM series VIEW views_index
 WHERE views = 0;
 ```
 
+## Atomic replacement of a secondary index {#atomic-index-replacement}
+
+You can atomically replace a secondary index. This can be useful if you want your index to become [covering](../../concepts/secondary_indexes.md#covering). This operation is totally transparent for your running applications: when you replace the index, the compiled queries are invalidated.
+
+To replace an existing index atomically, use the YDB CLI command [{{ ydb-cli }} table index rename](../../reference/ydb-cli/commands/secondary_index.md#rename) with the  `--replace` parameter.
+
 ## Performance of data writes to tables with secondary indexes {#write_performance}
 
 You need additional data structures to enable secondary indexes. Support for these structures makes table data update operations more costly.
diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md b/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md
index 84a59054a1f..4323a5ac4a4 100644
--- a/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md
+++ b/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md
@@ -1,6 +1,6 @@
 # Creating and deleting secondary indexes
 
-The `table index` command lets you create and delete [secondary indexes](../../../../concepts/secondary_indexes.md):
+By using the `table index` command, you can create and delete [secondary indexes](../../../../concepts/secondary_indexes.md):
 
 ```bash
 {{ ydb-cli }} [connection options] table index [subcommand] [options]
@@ -8,11 +8,13 @@ The `table index` command lets you create and delete [secondary indexes](../../.
 
 {% include [conn_options_ref.md](conn_options_ref.md) %}
 
-For information about the purpose and use of secondary indexes for app development, see [Secondary indexes](../../../../best_practices/secondary_indexes.md) in the "Recommendations" section.
+You can also add or delete a secondary index with the [ADD INDEX and DROP INDEX](../../../../yql/reference/syntax/alter_table.md#secondary-index) directives of YQL ALTER TABLE.
+
+To learn about secondary indexes and their use in application development, see [Secondary indexes](../../../../best_practices/secondary_indexes.md) under "Recommendations".
 
 ## Creating a secondary index {#add}
 
-A secondary index is created with `table index add`:
+Secondary indexes are created with the `table index add` command:
 
 ```bash
 {{ ydb-cli }} [connection options] table index add <sync-async> <table> \
@@ -21,41 +23,41 @@ A secondary index is created with `table index add`:
 
 Parameters:
 
-`<sync-async>`: Secondary index type. Set `global-sync` to build an index with [synchronous updates](../../../../concepts/secondary_indexes.md#sync) or `global-async` for an index with [asynchronous updates](../../../../concepts/secondary_indexes.md#async).
+`<sync-async>`: The type of the secondary index. Use `global-sync` to build an index [updated synchronously](../../../../concepts/secondary_indexes.md#sync) or `global-async` to build an index [updated asynchronously](../../../../concepts/secondary_indexes.md#async).
 
-`<table>`: Path and name of the table that the index is being built for.
+`<table>`: The path and name of the table you are building an index for
 
-`--index-name STR`: Required parameter that sets the index name. We recommend setting such index names that clearly indicate which columns they include. Index names are unique in the context of a table.
+`--index-name STR`: A mandatory parameter that sets the name of the index. It is recommended that you specify the names of such indexes, so that the columns included in them can be identified. Index names are unique in the context of the table.
 
-`--columns STR`: Required parameter that sets the structure and order of columns included in the index key. A list of comma-separated column names, without a space. The index key will consist of these columns with the columns of the table primary key added.
+`--columns STR`: A required parameter that defines the columns used in the index and their order in the index key. Column names are separated by a comma, with no spaces. The index key will include both the columns listed and the columns from the table's primary key.
 
-`--cover STR`: Optional parameter that sets the structure of [cover columns](../../../../concepts/secondary_indexes.md#cover) for the index. Their values won't be included in the index key, but will be copied to the entries in the index to get their values when searching by index without having to access the table.
+`--cover STR`: An optional parameter that defines the [covering columns](../../../../concepts/secondary_indexes.md#cover) of the index. Their values won't be added to the index key, but will be written to the index. This enables you to retrieve the values when searching the index without accessing the table.
 
-If the command is successful, a background build index operation is run and the operation ID is returned in the `id` field with semigraphics formatting to further get information about its status with the `operation get` command. To abort an incomplete build index operation, run the `operation cancel` command.
+When the command is executed, the DBMS starts building the index in the background, and the pseudographics-formatted `id` field shows the operation ID, so you can retrieve its status by `operation get`. When the index is being built, you can abort the process using `operation cancel`.
 
-Once the index build is either completed or aborted, you can delete the build operation record by running the `operation forget` command.
+To forget an index-building operation (either completed or terminated), use `operation forget`.
 
-To get information about the status of all build index operations, run the `operation list buildindex` command.
+To retrieve the status of all index-building operations, use `operation list buildindex`.
 
 **Examples**
 
 {% include [example_db1.md](../../_includes/example_db1.md) %}
 
-Adding a synchronous index by the `air_date` column to the `episodes` table from the [article on YQL](../../../../getting_started/yql.md) in the "Getting started" section:
+Adding a synchronous index built on the `air_date` column from the `episodes` table (see the [YQL article](../../../../getting_started/yql.md) under "Getting started"):
 
 ```bash
 {{ ydb-cli }} -p db1 table index add global-sync episodes \
   --index-name idx_aired --columns air_date
 ```
 
-Adding an asynchronous index by the `release_date` and `title` columns along with copying to the index the `series_info` column value for the `series` table from the [article on YQL](../../../../getting_started/yql.md) in the "Getting started" section:
+Adding an asynchronous index by the `release_date` and `title` columns, copying the `series_info` column value from the `series` table mentioned in the [YQL section](../../../../getting_started/yql.md) under "Getting started":
 
 ```bash
 {{ ydb-cli }} -p db1 table index add global-async series \
   --index-name idx_rel_title --columns release_date,title --cover series_info
 ```
 
-Output (the ID of the operation when it's actually run will be different):
+Result (the actual operation id might differ):
 
 ```text
 ┌──────────────────────────────────┬───────┬────────┐
@@ -65,7 +67,7 @@ Output (the ID of the operation when it's actually run will be different):
 └──────────────────────────────────┴───────┴────────┘
 ```
 
-Getting the operation status (use the actual operation ID):
+Getting the operation status (use the actual operation id):
 
 ```bash
 {{ ydb-cli }} -p db1 operation get ydb://buildindex/7?id=281474976866869
@@ -81,15 +83,14 @@ Returned value:
 └──────────────────────────────────┴───────┴─────────┴───────┴──────────┴─────────────────┴───────────┘
 ```
 
-Deleting information about the build index operation (use the actual operation ID):
-
+Deleting the index-building details (use the actual operation id):
 ```bash
 {{ ydb-cli }} -p db1 operation forget ydb://buildindex/7?id=2814749869
 ```
 
 ## Deleting a secondary index {#drop}
 
-A secondary index is deleted with `table index drop`:
+Secondary indexes are deleted by the `table index drop` command:
 
 ```bash
 {{ ydb-cli }} [connection options] table index drop <table> --index-name STR
@@ -99,9 +100,34 @@ A secondary index is deleted with `table index drop`:
 
 {% include [example_db1.md](../../_includes/example_db1.md) %}
 
-Deleting the `idx_aired` index built in the above index creation example from the episodes table:
+Deleting the `idx_aired` index from the episodes table (see the index-building example above):
 
 ```bash
 {{ ydb-cli }} -p db1 table index drop episodes --index-name idx_aired
 ```
 
+## Renaming a secondary index {#rename}
+
+To rename secondary indexes, use the `table index rename` command:
+
+```bash
+{{ ydb-cli }} [connection options] table index rename <table> --index-name STR --to STR
+```
+
+If an index with the new name exists, the command returns an error.
+
+To replace your existing index atomically, execute the rename command with the `--replace` option:
+
+```bash
+{{ ydb-cli }} [connection options] table index rename <table> --index-name STR --to STR --replace
+```
+
+**Example**
+
+{% include [example_db1.md](../../_includes/example_db1.md) %}
+
+Renaming the `idx_aired` index built on the episodes table (see the example of index creation above):
+
+```bash
+{{ ydb-cli }} -p db1 table index rename episodes --index-name idx_aired --to idx_aired_renamed
+```
diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
index 7402e472391..a09bf179f56 100644
--- a/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
+++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
@@ -46,6 +46,24 @@ ALTER TABLE `series` DROP INDEX `title_index`;
 
 You can also add or remove a secondary index using the {{ ydb-short-name }} CLI [table index](https://ydb.tech/en/docs/reference/ydb-cli/commands/secondary_index) command.
 
+## Renaming a secondary index {#rename-secondary-index}
+
+`RENAME INDEX`: Renames the index with the specified name.
+
+If an index with the new name exists, an error is returned.
+
+{% if backend_name == YDB %}
+
+Replacement of atomic indexes under load is supported by the command [{{ ydb-cli }} table index rename](../../../../reference/ydb-cli/commands/secondary_index.md#rename) in the {{ ydb-short-name }} CLI and by {{ ydb-short-name }} SDK ad-hoc methods.
+
+{% endif %}
+
+Example of index renaming:
+
+```sql
+ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
+```
+
 {% endif %}
 
 {% if feature_changefeed %}