---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ydb-platform--ydb.viewer.diplodoc.com/en/yql/reference/syntax/alter_table/indexes.md?version=v25.1
  - https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/alter_table/indexes.md?version=v25.1
  - href: ru/yql/reference/syntax/alter_table/indexes.md
    type: text/markdown
    title: Markdown version
  - href: ../../../../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: ru/core/yql/reference/syntax/alter_table/indexes.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb-platform--ydb.viewer.diplodoc.com/ru/llms.txt

# Добавление, удаление и переименование индекса


<!-- source: ru/_includes/not_allow_for_olap_note.md -->
{% note alert %}

<!-- source: ru/_includes/not_allow_for_olap_text.md -->
Поддерживается только для [строковых](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#row-oriented-tables) таблиц. Поддержка функциональности для [колоночных](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#column-oriented-tables) таблиц находится в разработке.
<!-- endsource: ru/_includes/not_allow_for_olap_text.md -->

{% endnote %}
<!-- endsource: ru/_includes/not_allow_for_olap_note.md -->

<!-- source: ru/_includes/vector_index_limitations.md -->
{% note alert %}

Фукциональность векторных индексов доступна, начиная с версии `25.1.2`. 
Для включения векторных индексов необходимо установить значение feature flag `enable_vector_index` в `true`.

В настоящее время не поддерживается:

* Обновление индекса: модифицировать основную таблицу можно, но существующий индекс не обновится. Нужно построить новый индекс, чтобы учесть изменения. При необходимости, можно [атомарно заменить](https://ydb-platform--ydb.viewer.diplodoc.com/ru/reference/ydb-cli/commands/secondary_index.md?version=v25.1#rename) существующий индекс на вновь построенный.
* Построение индекса для векторов c [битовым квантованием](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/udf/list/knn.md?version=v25.1#functions-convert).

Эти ограничения могут быть устранены в будущих версиях.

{% endnote %}
<!-- endsource: ru/_includes/vector_index_limitations.md -->


## Добавление индекса {#add-index}

`ADD INDEX` — добавляет индекс с указанным именем и типом для заданного набора колонок в строковых таблицах. Грамматика:

```yql
ALTER TABLE `<table_name>`
  ADD INDEX `<index_name>`
    [GLOBAL|LOCAL]
    [SYNC|ASYNC]
    [USING <index_type>]
    ON ( <index_columns> )
    [COVER ( <cover_columns> )]
    [WITH ( <parameter_name> = <parameter_value>[, ...])]
  [,   ...]
```

<!-- source: ru/yql/reference/syntax/_includes/index_grammar_explanation.md -->
* `GLOBAL/LOCAL` — глобальный или локальный индекс, в зависимости от типа индекса (`<index_type>`) может быть доступен только один из них:

    * `GLOBAL` — индекс, реализованный в виде отдельной таблицы или набора таблиц. Синхронное обновление такого индекса требует распределённых транзакций.  
    * `LOCAL` — локальный индекс в рамках шарда колоночной или строковой таблицы, не требует распределённых транзакций при обновлении, однако не обеспечивает прюнинг при поиске.

* `<index_name>` — уникальное имя индекса, по которому будет возможно обращение к данным.
* `SYNC/ASYNC` — синхронная или асинхронная запись в индекс. По умолчанию синхронная.
* `<index_type>` - тип индекса, в настоящее время поддерживаются:

    * `secondary` — вторичный индекс. Доступен только `GLOBAL`. Является значением по умолчанию.
    * `vector_kmeans_tree` — векторный индекс. Подробнее описан в [Векторный индекс](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/create_table/vector_index.md?version=v25.1).

* `<index_columns>` — список имён колонок создаваемой таблицы через запятую, по которому определяется состав и порядок включения колонок в ключ индекса. Обязательно должен быть указан. Ключ индекса будет состоять из этих колонок с добавлением колонок первичного ключа таблицы.
* `<cover_columns>` — список имён колонок создаваемой таблицы через запятую, которые будут сохранены в индексе дополнительно к колонкам ключа индекса, давая возможность получить дополнительные данные без обращения за ними в таблицу. По умолчанию пуст.
* `<parameter_name>` и `<parameter_value>` — параметры индекса, специфичные для конкретного `<index_type>`. Некоторые параметры индекса нельзя задать при его создании. См. [Изменение параметров индекса](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/alter_table/indexes.md?version=v25.1#alter-index).
<!-- endsource: ru/yql/reference/syntax/_includes/index_grammar_explanation.md -->

Параметры, специфичные для векторных индексов:

<!-- source: ru/yql/reference/syntax/_includes/vector_index_parameters.md -->
  * общие параметры для всех векторных индексов:
    * `vector_dimension` - размерность вектора эмбеддинга (16384 или меньше);
    * `vector_type` - тип значений вектора (`float`, `uint8`, `int8` или `bit`);
    * `distance` - функция расстояния (`cosine`, `manhattan` или `euclidean`), взаимосключающий с `similarity`;
    * `similarity` - функция схожести (`inner_product` или `cosine`), взаимосключающий с `distance`;
  * специфичные параметры для `vector_kmeans_tree` (см. [Векторный индекс типа `vector_kmeans_tree`](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/vector-indexes.md?version=v25.1#kmeans-tree-type)):
    * `clusters` - количество центроидов для алгоритма k-means (значения более 1000 могут ухудшить производительность);
    * `levels` - количество уровней в дереве;
<!-- endsource: ru/yql/reference/syntax/_includes/vector_index_parameters.md -->


Также добавить вторичный индекс можно с помощью команды [table index](https://ydb-platform--ydb.viewer.diplodoc.com/ru/reference/ydb-cli/commands/secondary_index.md?version=v25.1#add) YDB CLI.


### Примеры

Вторичный индекс:

```yql
ALTER TABLE `series`
  ADD INDEX `title_index`
  GLOBAL ON (`title`);
```

Векторный индекс:

```yql
ALTER TABLE `series`
  INDEX emb_cosine_idx GLOBAL SYNC USING vector_kmeans_tree
  ON (embedding) COVER (title)
  WITH (
    distance="cosine",
    vector_type="float",
    vector_dimension=512,
    clusters=128,
    levels=2
  );
```

## Изменение параметров индекса {#alter-index}

Индексы имеют параметры, зависящие от типа, которые можно настраивать. Глобальные индексы, [синхронные](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/secondary_indexes.md?version=v25.1#sync) или [асинхронные](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/secondary_indexes.md?version=v25.1#async), реализованы в виде скрытых таблиц, и их параметры автоматического партиционирования и реплик можно регулировать так же, как и настройки обычных таблиц.

{% note info %}

В настоящее время задание настроек партиционирования вторичных индексов при создании индекса не поддерживается ни в операторе [`ALTER TABLE ADD INDEX`](#add-index), ни в операторе [`CREATE TABLE INDEX`](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/create_table/secondary_index.md?version=v25.1).

{% endnote %}

```yql
ALTER TABLE <table_name> ALTER INDEX <index_name> SET <setting_name> <value>;
ALTER TABLE <table_name> ALTER INDEX <index_name> SET (<setting_name_1> = <value_1>, ...);
```

* `<table_name>` - имя таблицы, индекс которой нужно изменить.
* `<index_name>` - имя индекса, который нужно изменить.
* `<setting_name>` - имя изменяемого параметра, который должен быть одним из следующих:

  * [AUTO_PARTITIONING_BY_SIZE](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#auto_partitioning_by_size)
  * [AUTO_PARTITIONING_BY_LOAD](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#auto_partitioning_by_load)
  * [AUTO_PARTITIONING_PARTITION_SIZE_MB](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#auto_partitioning_partition_size_mb)
  * [AUTO_PARTITIONING_MIN_PARTITIONS_COUNT](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#auto_partitioning_min_partitions_count)
  * [AUTO_PARTITIONING_MAX_PARTITIONS_COUNT](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#auto_partitioning_max_partitions_count)
  * [READ_REPLICAS_SETTINGS](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/datamodel/table.md?version=v25.1#read_only_replicas)

{% note info %}

Эти настройки нельзя вернуть к исходным.

{% endnote %}

* `<value>` - новое значение параметра. Возможные значения включают:

  * `ENABLED` или `DISABLED` для параметров `AUTO_PARTITIONING_BY_SIZE` и `AUTO_PARTITIONING_BY_LOAD`
  * `"PER_AZ:<count>"` или `"ANY_AZ:<count>"` где `<count>` — число реплик для `READ_REPLICAS_SETTINGS`
  * для остальных параметров — целое число типа `Uint64`

### Пример

Код из следующего примера включает автоматическое партиционирование по нагрузке для индекса с именем `title_index` в таблице `series`, устанавливает минимальное количество партиций равным 5 и запускает по одной реплике в каждой зоне доступности (AZ) для каждой партиции:

```yql
ALTER TABLE `series` ALTER INDEX `title_index` SET (
    AUTO_PARTITIONING_BY_LOAD = ENABLED,
    AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 5,
    READ_REPLICAS_SETTINGS = "PER_AZ:1"
);
```

## Удаление индекса {#drop-index}

`DROP INDEX` — удаляет индекс с указанным именем. Приведенный ниже код удалит индекс с именем `title_index`.

```yql
ALTER TABLE `series` DROP INDEX `title_index`;
```


Также удалить индекс можно с помощью команды [table index](https://ydb-platform--ydb.viewer.diplodoc.com/ru/reference/ydb-cli/commands/secondary_index.md?version=v25.1#drop) YDB CLI.


## Переименование вторичного индекса {#rename-secondary-index}

`RENAME INDEX` — переименовывает индекс с указанным именем. Если индекс с новым именем существует, будет возвращена ошибка.


Возможность атомарной замены индекса под нагрузкой поддерживается командой [ydb table index rename](https://ydb-platform--ydb.viewer.diplodoc.com/ru/reference/ydb-cli/commands/secondary_index.md?version=v25.1#rename) YDB CLI и специализированными методами YDB SDK.


Пример переименования индекса:

```yql
ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
```