ydb docs best practices / secondary index

ref:59b71d37e6e31171270604e94f0388df0ca3bac4

20 files changed, 180 insertions, 331 deletions

diff --git a/ydb/docs/ru/core/best_practices/_includes/index.md b/ydb/docs/ru/core/best_practices/_includes/index.md
new file mode 100644
index 00000000000..3e630ac691b
--- /dev/null
+++ b/ydb/docs/ru/core/best_practices/_includes/index.md
@@ -0,0 +1,11 @@
+# Рекомендации
+
+В данном разделе собраны статьи, рассказывающие про назначение, особенности и лучшие практики применения инструментов YDB при разработке приложений.
+
+- [Проектирование схемы данных](../schema_design.md)
+- [Партиционирование таблиц](../table_sharding.md)
+- [Вторичные индексы](../secondary_indexes.md)
+- [Постраничный вывод](../paging.md)
+- [Загрузка больших объемов данных](../batch_upload.md)
+- [Использование таймаутов](../timeouts.md)
+  
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md b/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md
index 623fc098d8c..05ecdf0cbb6 100644
--- a/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md
+++ b/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md
@@ -1,110 +1,63 @@
 # Вторичные индексы
 
-В разделе описано, как использовать [вторичные индексы](../../concepts/secondary_indexes.md) для выборки данных.
+[Индексы](https://ru.wikipedia.org/wiki/Индекс_(базы_данных)) -- вспомогательные структуры в базах данных, позволяющие находить подходящие под определенный критерий данные без необходимости их полного перебора, а также получать отсортированные выборки без выполнения фактической сортировки, требующей обработки полного набора всех сортируемых данных.
 
-В общем случае транзакции с использованием глобального индекса являются [распределенными](../../concepts/transactions.md#distributed-tx). Запрос может быть выполнен как одношардовая транзакция в следующих случаях:
+Данные в таблицах YDB всегда проиндексированы по первичному ключу. Это означает, что получение любой записи из таблицы с заданными значениями полей, составляющих первичный ключ, всегда будет занимать минимальное фискированное время, вне зависимости от общего количества записей в таблице. Также наличие индекса по первичному ключу позволяет получить любой последовательный диапазон записей по возрастанию или убыванию первичного ключа. Время исполнения такой операции будет зависеть только от количества получаемых записей, но не зависеть от общего количества записей в таблице.
 
-* точечное чтение по первичному ключу;
-* точечное чтение по индексной колонке, если запрашиваемые данные представляют собой первичный ключ, его часть или имеется копия данных в индексе ([covering index](../../concepts/secondary_indexes.md#covering));
-* точечная слепая запись в таблицу с [асинхронным индексом](../../concepts/secondary_indexes.md#async).
+Для того, чтобы воспользоваться аналогичными возможностями для любых полей или комбинаций полей таблицы, по ним могут быть построены дополнительные индексы, называемые **вторичнымм индексами**.
 
-{% note warning %}
+Транзакционные системы применяет индексы для того, чтобы исключить деградацию производительности и повышение стоимости выполнения запросов при росте объема хранимых данных.
 
-Размер ответа клиенту не может превышать 50 МБ. Размер данных, извлекаемых из одного шарда таблицы в одном YQL-запросе, не может превышать 5 ГБ. Для больших таблиц и запросов эти ограничения могут сделать невозможным полный просмотр всех строк таблицы.
+В данной статье описаны основные операции по работе со вторичными индексами, и даны ссылки на подробные материалы по каждой операции. Информация о разных типах вторичных индексов и особенностях их устройства находится в статье [Вторичные индексы](../../concepts/secondary_indexes.md) раздела "Концепции". 
 
-{% endnote %}
+## Создание вторичных индексов {#create}
 
-## Создание таблицы {#create}
+Вторичный индекс является объектом схемы данных, и может быть определен при создании таблицы [командой YQL `CREATE TABLE`](../../yql/reference/syntax/create_table.md), или добавлен к ней позднее [командой YQL `ALTER TABLE`](../../yql/reference/syntax/alter_table.md).
 
-Чтобы создать таблицу `series`, выполните запрос:
+Команда [создания индекса `table index add`](../../reference/ydb-cli/commands/secondary_index.md#add) поддерживается в YDB CLI.
 
-```sql
-CREATE TABLE series
-(
-    series_id Uint64,
-    title Utf8,
-    series_info Utf8,
-    release_date Uint64,
-    views Uint64,
-    PRIMARY KEY (series_id),
-    INDEX views_index GLOBAL ON (views)
-);
-```
-
-Таблица `series` содержит ключевую колонку `series_id`. Индекс по первичному ключу в {{ ydb-short-name }} создается автоматически. Данные хранятся отсортированными по возрастанию значений первичного ключа, поэтому выборки по такому ключу будут эффективны. Пример такой выборки — поиск всех выпусков сериала по его `series_id` из таблицы `series`. Также создан индекс с именем `views_index` к колонке `views`, который позволит эффективно выполнять запросы используя ее в предикате.
+Так как индекс содержит собственные данные, являющиеся производными от данных в таблице, то при создании индекса на существующей таблице с данными будет выполнена операция начального построения индекса, которая может занимать продолжительное время. Данная операция выполняется в фоновом режиме, не блокирует работу с таблицей, но до окончания построения новым индексом воспользоваться будет невозможно.
 
-Для более сложной выборки можно создать несколько вторичных индексов. Например, чтобы создать таблицу `series` с двумя индексами, выполните запрос:
-
-```sql
-CREATE TABLE series
-(
-    series_id Uint64,
-    title Utf8,
-    series_info Utf8,
-    release_date Uint64,
-    views Uint64,
-    PRIMARY KEY (series_id),
-    INDEX views_index GLOBAL ON (views) COVER (release_date),
-    INDEX date_index GLOBAL ON (release_date)
-);
-```
+Использование индекса возможно только в порядке включенных в него полей. Если в индексе два поля `a` и `b`, то такой индекс может быть эффективно использован для запросов вида:
+- `where a=:1 and b=:2`
+- `where a=:1`
+- `where a>:1`, а также другие операторы сравнения
+- `where a=:1 and b>:2`, а также любые другие операторы сравнения, но первое поле должно проверяться на равенство
 
-Здесь созданы два вторичных индекса: `views_index` к колонке `views` и `date_index` к колонке `release_date`. Причем индекс `views_index` содержит копию данных из колонки `release_date`.
+При этом, такой индекс не может быть применен для следующих запросов:
+- `where b=:1`
+- `where a>:1 and b>:2`, точнее эта запись будет равнозначна `where a>:1` с точки зрения применения индекса
+- `where b>:2`
 
-{% note info %}
+С учетом описанной выше особенности, бесполезно пытаться заранее индексировать все возможные комбинации колонок в таблице в расчете на быстрое исполнение любых запросов. Индекс - это всегда компромисс между скоростью поиска и записи, а также занимаемым данными местом в хранилище. Индексы создаются под конкретные выборки и условия поиска, которые будут делаться приложением в базе данных.
 
-Возможно добавление вторичного индекса для существующей таблицы без остановки обслуживания. Подробнее об онлайн-создании индекса читайте в [инструкции](../../concepts/secondary_indexes.md#index-add).
+## Применение вторичных индексов при выборке данных {#use}
 
-{% endnote %}
-
-## Вставка данных {#insert}
-
-В примерах YQL-запросов используются [prepared queries](https://en.wikipedia.org/wiki/Prepared_statement). Чтобы выполнить их в YQL-редакторе, задайте значения параметров, которые объявлены с помощью инструкции `DECLARE`.
-
-Чтобы добавить данные в таблицу `series`, выполните запрос:
+Для обращения к таблице по вторичному индексу его имя должно быть явно указано в секции `view` после имени таблицы, как описано в статье про [команду `SELECT`](../../yql/reference/syntax/select#secondary_index) YQL. Например, для получения из таблицы Заказов (`orders`) выборки заказов клиента с заданным ID (`id_customer`) запрос будет выглядеть следующим образом:
 
 ```sql
-DECLARE $seriesId AS Uint64;
-DECLARE $title AS Utf8;
-DECLARE $seriesInfo AS Utf8;
-DECLARE $releaseDate AS Uint32;
-DECLARE $views AS Uint64;
-
-INSERT INTO series (series_id, title, series_info, release_date, views)
-VALUES ($seriesId, $title, $seriesInfo, $releaseDate, $views);
+SELECT * 
+FROM   orders as o view idx_customer
+WHERE  o.id_customer = :1
 ```
 
-## Изменение данных {#upsert}
+, где `idx_customer` -- имя вторичного индекса на таблице `orders`, первым в котором указано поле `id_customer`.
 
-Сохранить в БД новое значение количества просмотров для определенного сериала можно с помощью операции `UPSERT`.
+Без указания секции `view` для выполнения такого запроса будет полностью просканирована таблица `orders`.
 
-Чтобы изменить данные в таблице `series`, выполните запрос:
+В транзакционных приложениях подобные информационные запросы выполняются с использованием поcтраничного вывода данных, что исключает рост стоимости и времени исполнения при увеличении количества записей, подходящих под условия фильтрации. Описанный на примере первичного ключа подход к написанию [постраничных запросов](../paging.md) применим также и к колонкам, включенным во вторичный индекс.
 
-```sql
-DECLARE $seriesId AS Uint64;
-DECLARE $newViews AS Uint64;
+## Проверка стоимости запроса {#cost}
 
-UPSERT INTO series (series_id, views)
-VALUES ($seriesId, $newViews);
-```
+Любой запрос в транзакционном приложении необходимо проверять с точки зрения того, сколько он выполнил операций ввода-вывода в базе данных, и сколько CPU было потрачено на его исполнение. Также необходимо убедиться, что эти цифры не растут бесконечно с ростом объема базы данных. В YDB после выполнения каждого запроса возвращается статистика, содержащая необходимую для анализа информацию.
 
-## Выборка данных {#select}
-
-Без использования вторичных индексов запрос на выборку записей, которые удовлетворяют заданному предикату по количеству просмотров, будет работать неэффективно, так как для его выполнения {{ ydb-short-name }} просканирует все строки таблицы `series`. В запросе необходимо явно указать, какой индекс использовать.
-
-Чтобы выбрать строки из таблицы `series`, удовлетворяющие предикату по количеству просмотров, выполните запрос:
-
-```sql
-SELECT series_id, title, series_info, release_date, views
-FROM series view views_index
-WHERE views >= someValue
-```
+При использовании YDB CLI вывод статистики после исполнения команды `yql` включается опцией `--stats`. Все YDB SDK также содержат структуры, содержащие статистику после исполнения запросов. При исполнении запросов в UI рядом с закладкой результатов также присутствует закладка со статистикой.
 
 ## Обновление данных с использованием вторичного индекса {#update}
 
-Инструкция `UPDATE` не позволяет указать на использование вторичного индекса для поиска данных, поэтому попытка выполнить `UPDATE ... WHERE indexed_field = $value` приведет к полному сканированию таблицы. Чтобы избежать этого, можно предварительно выполнить `SELECT` по индексу с получением значения первичного ключа, а затем выполнить `UPDATE` по первичному ключу. Также можно воспользоваться инструкцией `UPDATE ON`.
+Команды YQL изменения записей ([`UPDATE`](../../yql/reference/syntax/update.md), [`UPSERT`](../../yql/reference/syntax/upsert_into.md), [`REPLACE`](../../yql/reference/syntax/replace_into.md)) не позволяют указать на использование вторичного индекса для поиска данных, поэтому попытка выполнить `UPDATE ... WHERE indexed_field = $value` приведет к полному сканированию таблицы. Чтобы избежать этого, можно предварительно выполнить `SELECT` по индексу с получением значения первичного ключа, а затем выполнить `UPDATE` по первичному ключу. Также можно воспользоваться инструкцией `UPDATE ON`.
 
-Чтобы обновить данные в таблице `series`, выполните запрос:
+Чтобы обновить данные в таблице `table1`, выполните запрос:
 
 ```sql
 $to_update = (
@@ -127,3 +80,11 @@ SELECT series_id,
 FROM series view views_index
 WHERE views == 0;
 ```
+
+## Производительность записи в таблицы со вторичными индексами {#write_performance}
+
+Для работы вторичных индексов необходимы дополнительные структуры данных. Поддержка этих структур приводит к повышению стоимости операций изменения данных в таблицах. 
+
+При синхронном обновлении индексов транзакция подтверждается только после записи всех необходимых данных, как в таблице, так и в синхронных индексах. Это приводит как к увеличению времени исполнения, так и к необходимости применения координируемых транзакций даже при добавлении или изменении записей в единственной партиции.
+
+Асинхронно обновляемые индексы сохраняют возможность применения одношардовых транзакций, однако гарантируют только консистентность "в конечном счете", и все равно создают нагрузку на базу данных.
diff --git a/ydb/docs/ru/core/best_practices/_includes/timeouts.md b/ydb/docs/ru/core/best_practices/_includes/timeouts.md
index 52e20c75ee0..e75d2563687 100644
--- a/ydb/docs/ru/core/best_practices/_includes/timeouts.md
+++ b/ydb/docs/ru/core/best_practices/_includes/timeouts.md
@@ -2,31 +2,32 @@
 title: Использование таймаутов в YDB
 description: 'Значение operation_timeout определяет время, в течение которого результат запроса интересен пользователю. Если за данное время операция не выполнилась, сервер возвращает ошибку c кодом Timeout и попытается прекратить выполнение запроса, однако отмена запроса не гарантируется. Всегда рекомендуется устанавливать и таймаут на операцию, и транспортный таймаут. '
 ---
+# Использование таймаутов
 
 В разделе приведено описание доступных таймаутов и представлены примеры использования на различных языках программирования.
 
-## Предпосылки к использованию таймаутов
+## Предпосылки к использованию таймаутов {#intro}
 
 Механизм таймаутов в {{ ydb-short-name }} призван решить следующие проблемы:
 
 * Не дать запросу выполнятся так долго, что результат запроса становится не интересен для дальнейшего использования.
-* Обнаружить проблем сетевой связанности.
+* Обнаружить проблемы сетевой связности.
 
 Оба этих случая важны для обеспечения отказоустойчивости системы в целом. Рассмотрим таймауты подробнее.
 
-## Таймаут на операцию
+## Таймаут на операцию {#operational}
 
 Значение ``operation_timeout`` определяет время, в течение которого результат запроса интересен пользователю. Если за данное время операция не выполнилась, сервер возвращает ошибку c кодом ``Timeout`` и попытается прекратить выполнение запроса, однако отмена запроса не гарантируется. Таким образом, запрос, на который пользователю была возвращена ошибка ``Timeout``, может быть как успешно выполнен на сервере, так и отменен.
 
-## Таймаут отмены операции
+## Таймаут отмены операции {#cancel}
 
 Значение ``cancel_after`` определяет время, через которое сервер начнет отмену запроса, если отменить запрос возможно. В случае успешной отмены запроса сервер вернет ошибку с кодом ``Cancelled``.
 
-## Транспортный таймаут
+## Транспортный таймаут {#transport}
 
 На каждый запрос клиент должен выставить транспортный таймаут. Данное значение позволяет определить количество времени, которое клиент готов ждать ответа от сервера. Если за данное время сервер не ответил, то клиенту будет возвращена транспортная ошибка c кодом ``DeadlineExceeded``. Важно выставить такое значение клиентского таймаута чтоб при нормальной работе приложения и сети транспортные таймауты не срабатывали.
 
-## Применение таймаутов
+## Применение таймаутов {#usage}
 
 Всегда рекомендуется устанавливать и таймаут на операцию и транспортный таймаут. Значение транспортного таймаута следует делать на 50-100 миллисекунд больше чем значение таймаута на операцию, чтобы оставался некоторый запас времени, за который клиент сможет получить серверную ошибку c кодом ``Timeout``.
 
diff --git a/ydb/docs/ru/core/best_practices/index.md b/ydb/docs/ru/core/best_practices/index.md
index f98c34671b7..eb2590567da 100644
--- a/ydb/docs/ru/core/best_practices/index.md
+++ b/ydb/docs/ru/core/best_practices/index.md
@@ -1 +1 @@
-В данном разделе собраны статьи с рекомендациями по использованию функций {{ ydb-short-name }}.
+{% include [_includes/index.md](_includes/index.md) %}
\ No newline at end of file
diff --git a/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md b/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md
index d583b62884d..c62eb248711 100644
--- a/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md
+++ b/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md
@@ -37,7 +37,7 @@
 
     Индекс готов к использованию.
 
-Возможные влияния на пользовательские транзакции:
+Возможное влияние на пользовательские транзакции:
 
 * Может наблюдаться увеличение задержек из-за того, что транзакции становятся распределенными (при создании синхронного индекса).
 * Возможен повышенный фон ошибок `OVERLOADED` из-за того, что во время записи данных активно работает автоматическое разделение шардов индексной таблицы.
@@ -46,189 +46,15 @@
 
 Создание индекса — асинхронная операция. Если после запуска операции произойдет разрыв клиент-серверной связности, то построение индекса будет продолжено. Управлять асинхронной операцией можно через {{ ydb-short-name }} CLI.
 
-## Примеры работы со вторичным индексом {#example}
+## Создаени и удаление вторичных индексов {#ddl}
 
-### Создание вторичного индекса {#add}
+Вторичный индекс может быть:
 
-{% list tabs %}
+- Создан ири создании таблицы командой YQL [`CREATE TABLE`](../../yql/reference/syntax/create_table.md).
+- Добавлен к существующей таблице командой YQL [`ALTER TABLE`](../../yql/reference/syntax/alter_table.md) или командой YDB CLI [`table index add`](../../reference/ydb-cli/commands/secondary_index.md#add)
+- Удален у существующей таблицы командой YQL [`ALTER TABLE`](../../yql/reference/syntax/alter_table.md) или командой YDB CLI [`table index drop`](../../reference/ydb-cli/commands/secondary_index.md#drop).
+- Удален вместе с таблицей командой YQL [`DROP TABLE`](../../yql/reference/syntax/drop_table.md) или командой YDB CLI `table drop`.
 
-- CLI
+## Назначение и применение вторичных индексов {#best_practices}
 
-  Выполните команду:
-
-  ```bash
-  {{ ydb-cli }} \
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    table index add global[-sync|-async] \
-    --index-name title_index \
-    --columns title \
-    series
-  ```
-
-  * `--endpoint` — эндпоинт БД.
-  * `--database` — полный путь к БД.
-  * `-sync|-async` — тип индекса.
-  * `--index-name` — имя создаваемого индекса.
-  * `--columns` — список колонок, по которым будет создан индекс.
-
-  При необходимости можно продублировать данные в индекс, добавив опцию `--cover` — список колонок, данные из которых будут скопированы в данный индекс.
-
-  Таким образом, команда создания индекса принимает вид:
-
-  ```bash
-  {{ ydb-cli }} \
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    table index add global[-sync|-async] \
-    --index-name title_index \
-    --columns title \
-    --cover release_date \
-    series
-  ```
-
-  Результат:
-
-  ```text
-  ┌────────────────────────────────────────┬───────┬────────┐
-  | id                                     | ready | status |
-  ├────────────────────────────────────────┼───────┼────────┤
-  | ydb://buildindex/7?id=1407375091598308 | false |        |
-  └────────────────────────────────────────┴───────┴────────┘
-  ```
-
-  Будет запущена операция построения индекса, `id` — идентификатор операции.
-
-- YQL
-
-  Выполните запрос:
-
-  ```sql
-  ALTER TABLE `series` ADD INDEX `title_index` GLOBAL [SYNC|ASYNC] ON (`title`);
-  ```
-
-  При необходимости можно продублировать данные в индекс, использовав ключевое слово `COVER`:
-
-  ```sql
-  ALTER TABLE `series` ADD INDEX `title_index` GLOBAL [SYNC|ASYNC] ON (`title`) COVER(`release_date`);
-  ```
-
-  Будет запущено построение индекса, дождитесь завершения операции.
-  
-  {% note warning %}
-  
-  Отменить построение средствами YQL невозможно, при необходимости используйте {{ ydb-short-name }} CLI.
-
-  {% endnote %}
-
-{% endlist %}
-
-{% note info %}
-
-Если не указать тип индекса, то по умолчанию будет создан синхронный индекс.
-
-{% endnote %}
-
-### Получение состояния операции построения вторичного индекса {#get}
-
-{% list tabs %}
-
-- CLI
-
-  Выполните команду:
-
-  ```bash
-  {{ ydb-cli }} \
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    operation get ydb://buildindex/7?id=1407375091598308
-  ```
-
-  * `--endpoint` — эндпоинт БД.
-  * `--database` — полный путь к БД.
-
-  Результат:
-
-  ```text
-  ┌────────────────────────────────────────┬───────┬─────────┬───────┬──────────┬───────────────────────────────────────────────────────────────┬─────────────┐
-  | id                                     | ready | status  | state | progress | table                                                         | index       |
-  ├────────────────────────────────────────┼───────┼─────────┼───────┼──────────┼───────────────────────────────────────────────────────────────┼─────────────┤
-  | ydb://buildindex/7?id=1407375091598308 | true  | SUCCESS | Done  | 100.00%  | /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj/series | title_index |
-  └────────────────────────────────────────┴───────┴─────────┴───────┴──────────┴───────────────────────────────────────────────────────────────┴─────────────┘
-  ```
-
-{% endlist %}
-
-### Отмена операции построения вторичного индекса {#cancel}
-
-{% list tabs %}
-
-- CLI
-
-  Выполните команду:
-
-  ```bash
-  {{ ydb-cli }} \
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    operation cancel ydb://buildindex/7?id=1407375091598308
-  ```
-
-  * `--endpoint` — эндпоинт БД.
-  * `--database` — полный путь к БД.
-
-{% endlist %}
-
-### Удаление завершенной или отмененной операции построения вторичного индекса {#forget}
-
-{% list tabs %}
-
-- CLI
-
-  Выполните команду:
-
-  ```bash
-  {{ ydb-cli }} \
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    operation forget ydb://buildindex/7?id=1407375091598308
-  ```
-
-  * `--endpoint` — эндпоинт БД.
-  * `--database` — полный путь к БД.
-
-{% endlist %}
-
-### Удаление вторичного индекса {#drop}
-
-{% list tabs %}
-
-- CLI
-
-  Выполните команду:
-
-  ```bash
-    --endpoint ydb.serverless.yandexcloud.net:2135 \
-    --database /ru-central1/b1g4ej5ju4rf5kelpk4b/etn01lrprvnlnhv8v5kj \
-    table index drop \
-    --index-name title_index \
-    series
-  ```
-
-  * `--endpoint` — эндпоинт БД.
-  * `--database` — полный путь к БД.
-  * `--index-name` — имя удаляемого индекса.
-
-- YQL
-
-  Выполните запрос:
-
-  ```sql
-  ALTER TABLE `series` DROP INDEX `title_index`;
-  ```
-
-{% endlist %}
-
-#### Что дальше
-
-Другие примеры работы с вторичными индексами смотрите в [рекомендациях](../../best_practices/secondary_indexes.md).
+О нзначении и применении вторичных индексов при разработке приложений смотрите в [рекомендациях](../../best_practices/secondary_indexes.md).
diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
index a26ffacf37d..63610403ed2 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
@@ -54,10 +54,9 @@ scripting yql | Выполнение YQL-скрипта
 table attribute add | Добавление атрибута таблицы
 table attribute drop | Удаление атрибута таблицы
 table drop | Удаление таблицы
-[table index add global](../commands/index-ops.md) | Добавление синхронного индекса 
-[table index add global-async](../commands/index-ops.md) | Добавление асинхронного индекса 
-[table index add global-sync](../commands/index-ops.md) | Добавление синхронного индекса 
-[table index drop](../commands/index-ops.md) | Удаление индекса
+[table index add global-async](../commands/secondary_index.md#add) | Добавление асинхронного индекса 
+[table index add global-sync](../commands/secondary_index.md#add) | Добавление синхронного индекса 
+[table index drop](../commands/secondary_index.md#drop) | Удаление индекса
 [table query execute](../commands/query.md) | Исполнение YQL-запроса
 [table query explain](../commands/explain-plan.md) | План исполнения YQL-запроса
 [table readtable](../commands/readtable.md) | Потоковое чтение таблицы
diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md
index 2ad62c0090a..8e296e3e2d1 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md
@@ -15,6 +15,6 @@
 * [Работа с директориями](../commands/dir.md).
 * [Выполнение запроса к данным](../commands/query.md).
 * [Потоковое чтение таблицы](../commands/readtable.md).
-* [Работа со вторичными индексами](../commands/index-ops.md).
+* [Работа со вторичными индексами](../commands/secondary_index.md).
 * [Получение списка эндпоинтов для базы данных](../commands/discovery-list.md).
 * [Нагрузочное тестирование](../commands/workload/index.md).
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/all-get.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/all-get.md
deleted file mode 100644
index 78e19dde910..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/all-get.md
+++ /dev/null
@@ -1,7 +0,0 @@
-## Получение информации обо всех операциях построения индекса для базы {#all-get}
-
-Посмотрите все операции построения индекса для БД:
-
-```bash
-{{ ydb-cli }} operation list buildindex
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/delete-index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/delete-index.md
deleted file mode 100644
index e1859667770..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/delete-index.md
+++ /dev/null
@@ -1,9 +0,0 @@
-## Удаление индекса {#delete-index}
-
-Если индекс не нужен, то его можно удалить. Удаление индекса — обычный синхронный запрос. Результат возвращается сразу по исполнению запроса.
-
-Удалите индекс:
-
-```bash
-{{ ydb-cli }} table index drop --index-name title_index series
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/intro.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/intro.md
deleted file mode 100644
index 2755f41c533..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/intro.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Работа со вторичными индексами
-
-В разделе описано, как управлять вторичными индексами. Добавление вторичного индекса выполняется в асинхронном режиме. После запуска такой команды {{ ydb-short-name }} CLI сразу выдает информацию об операции и дает пользователю возможность продолжить работу.
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get-exp.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get-exp.md
deleted file mode 100644
index f6d58bc616e..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get-exp.md
+++ /dev/null
@@ -1,4 +0,0 @@
-Где:
-
-* `progress` — процент шардов исходной таблицы, завершивших трансфер данных.
-* `status` — Результат всей операции построения. Отображается, когда операция уже завершена.
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get.md
deleted file mode 100644
index 19edf2d62ad..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/one-get.md
+++ /dev/null
@@ -1,7 +0,0 @@
-## Получение информации о выполнении операции {#one-get}
-
-Чтобы получить информацию о ходе добавления вторичного индекса, проверьте статус операции:
-
-```bash
-{{ ydb-cli }} operation get ydb://buildindex/7?id=562950460138467
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operation-index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operation-index.md
deleted file mode 100644
index 2a56101404a..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operation-index.md
+++ /dev/null
@@ -1,9 +0,0 @@
-## Добавление вторичного индекса {#operation-index}
-
-Добавьте индекс `title_index` по колонке `title` таблицы `series`:
-
-```bash
-{{ ydb-cli }} table index add global \
-  --index-name title_index \
-  --columns title series
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operations-index-exp.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operations-index-exp.md
deleted file mode 100644
index 542de44b777..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/operations-index/operations-index-exp.md
+++ /dev/null
@@ -1 +0,0 @@
-Где `id` — идентификатор операции построения индекса.
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md
new file mode 100644
index 00000000000..916199e2c21
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md
@@ -0,0 +1,105 @@
+# Создание и удаление вторичных индексов
+
+Команда `table index` позволяет создавать и удалять [вторичные индексы](../../../../concepts/secondary_indexes.md):
+
+```bash
+{{ ydb-cli }} [connection options] table index [subcommand] [options]
+```
+
+{% include [conn_options_ref.md](conn_options_ref.md) %}
+
+О назначении и применениии вторичных индексов при разработке приложений можно прочитать в статье [Вторичные индексы](../../../../best_practices/schema_design.md) в разделе "Рекомендации".
+
+## Создание вторичного индекса {#add}
+
+Создание вторичного индекса выполняется командой `table index add`:
+
+```bash
+{{ ydb-cli }} [connection options] table index add <sync_async> <table> \
+  --index-name STR --columns STR [--cover STR]
+```
+
+Параметры:
+
+`<sync_async>` : Тип вторичного индекса. Укажите `global_sync` для построения индекса [с синхронным обновлением](../../../../concepts/secondary_indexes.md#sync), или `global_async` для индекса [с асинхронным обновлением](../../../../concepts/secondary_indexes.md#async).
+
+`<table>`: Путь и имя таблицы, для которой выполняется построение индекса
+
+`--index-name STR`: Обязательный параметр, в котором задается имя индекса. Рекомендуется определять такие имена индексов, чтобы по ним можно было понять какие колонки в них включены. Имена индексов уникальны в контексте таблицы.
+
+`--columns STR`: Обязательный параметр, в котором определяются состав и порядок включения колонок в ключ индекса. Перечисляются имена колонок через запятую, без пробелов. Ключ индекса будет состоять из этих колонок с добавлением колонок первичного ключа таблицы.
+
+`--cover STR`: Необязательный параметр, в котором определяется состав [покрывающих колонок](../../../../concepts/secondary_indexes.md#cover) индекса. Их значеня не будет включены в состав ключа индекса, но будут скопированы в записи в индексе для получения их значений при поиске по индексу без необходимости обращения к таблице.
+
+В результате успешного исполнения команды запускается фоновая операция построения индекса, и в выделенном псевдографикой поле `id` возвращается идентификатор операции для дальнейшего получения информации о её статусе командой `operation get`. Незаконченное построение индекса может быть прервано командой `operation cancel`.
+
+После того, как построение индекса завершено (успешно или прервано), запись об операции построения может быть удалена командой `operation forget`.
+
+Получить информацию о статусе всех операций построения индекса можно командой `operation list buildindex`.
+
+**Примеры**
+
+{% include [example_db1.md](../../_includes/example_db1.md) %}
+
+Добавление синхронного индекса по колонке `air_date` в таблицу `episodes` из [статьи про YQL](../../../../getting_started/yql.md) в разделе "Начало работы":
+
+```bash
+{{ ydb-cli }} -p db1 table index add global-sync episodes \
+  --index-name idx_aired --columns air_date
+```
+
+Добавление асинхронного индекса по колонкам `release_date` и `title`, и с копированием в индекс значения колонки `series_info`, для таблицы `series` из [статьи про YQL](../../../../getting_started/yql.md) в разделе "Начало работы":
+
+```bash
+{{ ydb-cli }} -p db1 table index add global-async series \
+  --index-name idx_rel_title --columns release_date,title --cover series_info
+```
+
+Вывод (id операции при фактическом запуске будет другой):
+
+``` text
+┌──────────────────────────────────┬───────┬────────┐
+| id                               | ready | status |
+├──────────────────────────────────┼───────┼────────┤
+| ydb://buildindex/7?id=2814749869 | false |        |
+└──────────────────────────────────┴───────┴────────┘
+```
+
+Получение информации о статусе операции (подставьте фактический id операции):
+
+```bash
+{{ ydb-cli }} -p db1 operation get ydb://buildindex/7?id=281474976866869
+```
+
+Возвращаемое значение:
+
+``` text
+┌──────────────────────────────────┬───────┬─────────┬───────┬──────────┬─────────────────┬───────────┐
+| id                               | ready | status  | state | progress | table           | index     |
+├──────────────────────────────────┼───────┼─────────┼───────┼──────────┼─────────────────┼───────────┤
+| ydb://buildindex/7?id=2814749869 | true  | SUCCESS | Done  | 100.00%  | /local/episodes | idx_aired |
+└──────────────────────────────────┴───────┴─────────┴───────┴──────────┴─────────────────┴───────────┘
+```
+
+Удаление информации о построении индекса (подставьте фактический id операции):
+```bash
+{{ ydb-cli }} -p db1 operation forget ydb://buildindex/7?id=2814749869
+```
+
+## Удаление вторичного индекса {#drop}
+
+Удаление вторичного индекса выполняется командой `table index drop`:
+
+```bash
+{{ ydb-cli }} [connection options] table index drop <table> --index-name STR
+```
+
+**Пример**
+
+{% include [example_db1.md](../../_includes/example_db1.md) %}
+
+Удаление индекса `idx_aired` с таблицы episodes, построенного в примере создания индекса выше:
+
+```bash
+{{ ydb-cli }} -p db1 table index drop episodes --index-name idx_aired
+```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/index-ops.md b/ydb/docs/ru/core/reference/ydb-cli/commands/index-ops.md
deleted file mode 100644
index 8905766ce62..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/index-ops.md
+++ /dev/null
@@ -1,13 +0,0 @@
-{% include [intro.md](_includes/operations-index/intro.md) %}
-
-{% include [operation-index.md](_includes/operations-index/operation-index.md %}
-
-{% include [operations-index-exp.md](_includes/operations-index/operations-index-exp.md) %}
-
-{% include [one-get.md](_includes/operations-index/one-get.md) %}
-
-{% include [one-get-exp.md](_includes/operations-index/one-get-exp.md) %}
-
-{% include [all-get.md](_includes/operations-index/all-get.md) %}
-
-{% include [delete-index.md](_includes/operations-index/delete-index.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/secondary_index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/secondary_index.md
new file mode 100644
index 00000000000..4c7071ffe79
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/secondary_index.md
@@ -0,0 +1 @@
+{% include [_includes/secondary_index.md](_includes/secondary_index.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/tools/dump.md b/ydb/docs/ru/core/reference/ydb-cli/commands/tools/dump.md
deleted file mode 100644
index 1e037347621..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/tools/dump.md
+++ /dev/null
@@ -1 +0,0 @@
-{% include [dump.md](../../_includes/commands/tools/dump.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/tools/restore.md b/ydb/docs/ru/core/reference/ydb-cli/commands/tools/restore.md
deleted file mode 100644
index 82ca1b170cb..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/tools/restore.md
+++ /dev/null
@@ -1 +0,0 @@
-{% include [restore.md](../../_includes/commands/tools/restore.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
index cfbd425f39f..d95f5d2b19e 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -17,6 +17,8 @@ items:
       href: commands/scheme-describe.md
     - name: Директории
       href: commands/dir.md
+    - name: Вторичные индексы
+      href: commands/secondary_index.md
     - name: Переименование таблиц
       href: commands/tools/rename.md
   - name: Работа с данными
@@ -27,8 +29,6 @@ items:
       href: commands/explain-plan.md
     - name: Потоковое чтение таблицы
       href: commands/readtable.md
-    - name: Работа со вторичными индексами
-      href: commands/index-ops.md
     - name: Скан запросы
       href: commands/scan-query.md
   - name: Загрузка и выгрузка данных