--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/yql/reference/syntax/alter_table/indexes.md?version=main - https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main sourcePath: ru/core/yql/reference/syntax/alter_table/indexes.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Добавление, удаление и переименование индекса ## Добавление индекса {#add-index} `ADD INDEX` — добавляет индекс с указанным именем и типом для заданного набора колонок в строковых таблицах. Грамматика: ```yql ALTER TABLE `` ADD INDEX `` [GLOBAL|LOCAL] [UNIQUE] [SYNC|ASYNC] [USING ] ON ( ) [COVER ( )] [WITH ( = [, ...])] [, ...] ``` * `GLOBAL/LOCAL` — глобальный или локальный индекс, в зависимости от типа индекса (``) может быть доступен только один из них: * `GLOBAL` — индекс, реализованный в виде отдельной таблицы или набора таблиц. Синхронное обновление такого индекса требует распределённых транзакций. * `LOCAL` — локальный индекс в рамках шарда колоночной или строковой таблицы, не требует распределённых транзакций при обновлении, однако не обеспечивает прюнинг при поиске. * `` — уникальное имя индекса, по которому будет возможно обращение к данным. * `SYNC/ASYNC` — признак синхронности индекса. * `SYNC` - [синхронный](https://ydb.tech/docs/ru/concepts/query_execution/secondary_indexes.md?version=main#sync) индекс. Значение по умолчанию. * `ASYNC` - [асинхронный](https://ydb.tech/docs/ru/concepts/query_execution/secondary_indexes.md?version=main#async) индекс. * `UNIQUE` — признак [уникального вторичного индекса](https://ydb.tech/docs/ru/concepts/query_execution/secondary_indexes.md?version=main#unique). Уникальный индекс должен быть глобальным синхронным (`GLOBAL UNIQUE SYNC`) и не должен содержать конструкцию `USING `. * `` - тип индекса, в настоящее время поддерживаются: * `secondary` — вторичный индекс. Для вторичных индексов доступен только режим `GLOBAL`. Это тип индекса по умолчанию. * `vector_kmeans_tree` — векторный индекс. Подробнее описан в разделе [Векторный индекс](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/vector_index.md?version=main). * `fulltext_plain` — базовый полнотекстовый индекс. Подробнее описан в [Полнотекстовый индекс](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/fulltext_index.md?version=main). * `fulltext_relevance` — полнотекстовый индекс со статистикой [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) для расчёта релевантности. Подробнее описан в [Полнотекстовый индекс](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/fulltext_index.md?version=main). * `json` — JSON-индекс для ускорения предикатов `JSON_EXISTS` и `JSON_VALUE` по колонке типа `Json` или `JsonDocument`. Подробнее описан в [JSON-индекс](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/json_index.md?version=main). * `bloom_filter` — локальный Блум-индекс. Доступен только `LOCAL`. См. [ALTER TABLE ADD INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-bloom). * `bloom_ngram_filter` — локальный N-граммный Блум-индекс. Доступен только `LOCAL`. См. [ALTER TABLE ADD INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-bloom). * `min_max` — локальный min/max-индекс. Доступен только `LOCAL`. См. [ALTER TABLE ADD INDEX](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#local-min-max). * `` — список имён колонок создаваемой таблицы через запятую, по которому определяется состав и порядок включения колонок в ключ индекса. Обязательно должен быть указан. Ключ индекса будет состоять из этих колонок с добавлением колонок первичного ключа таблицы. * `` — список имён колонок создаваемой таблицы через запятую, которые будут сохранены в индексе дополнительно к колонкам ключа индекса, давая возможность получить дополнительные данные без обращения за ними в таблицу. По умолчанию пуст. * `` и `` — параметры индекса, специфичные для конкретного ``. Некоторые параметры индекса нельзя задать при его создании. См. [Изменение параметров индекса](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/indexes.md?version=main#alter-index). Также добавить вторичный индекс можно с помощью команды [table index](https://ydb.tech/docs/ru/reference/ydb-cli/commands/secondary_index.md?version=main#add) YDB CLI. Параметры для всех типов индексов: * `parallel` - максимальное число параллельных обработчиков на основе [партиций](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#partition), задействованных в построении индекса (целое число между `1` и `MaxBuildIndexShardsInFlight` из `SchemeShardConfig`). - Если параметр не указан, сейчас используется значение по умолчанию `32` или `MaxBuildIndexShardsInFlight`, если это значение меньше. `MaxBuildIndexShardsInFlight` по умолчанию равен `1000`. В будущих версиях логика выбора параллелизма по умолчанию может быть изменена. - Вы можете установить меньший лимит, чтобы снизить влияние построения индекса на производительность базы данных. - Вы также можете установить больший лимит, чтобы ускорить построение индекса, если у вас достаточно аппаратных ресурсов. Параметры, специфичные для векторных индексов: * общие параметры для всех векторных индексов: * `vector_dimension` - размерность вектора эмбеддинга (значение от 1 до 16384); * `vector_type` - тип значений вектора (`float`, `uint8` или `int8`); * `distance` - [функция расстояния](https://ydb.tech/docs/ru/yql/reference/udf/list/knn.md?version=main#functions-distance) (`cosine`, `manhattan` или `euclidean`), взаимосключающий с `similarity`; * `similarity` - [функция схожести](https://ydb.tech/docs/ru/yql/reference/udf/list/knn.md?version=main#functions-distance) (`inner_product` или `cosine`), взаимосключающий с `distance`; * специфичные параметры для `vector_kmeans_tree` ([подробнее о типе индекса](https://ydb.tech/docs/ru/dev/vector-indexes.md?version=main#kmeans-tree-type)): * `clusters` - количество центроидов для алгоритма k-means (значение от 2 до 2048); * `levels` - количество уровней в дереве (значение от 1 до 16); * `overlap_clusters` - число ближайших кластеров, в которые будет добавлен каждый вектор (по умолчанию 1); * `adaptive_clusters` - для [индексов с фильтрацией](https://ydb.tech/docs/ru/dev/vector-indexes.md?version=main#filtered) автоматически выбирать количество кластеров для каждого значения фильтруемой колонки в зависимости от количества векторов у этого значения (`true` или `false`, по умолчанию `false`). Подробнее см. [Адаптивное количество кластеров](https://ydb.tech/docs/ru/dev/vector-indexes-kmeans-tree-type.md?version=main#adaptive-clusters); * общее количество узлов в дереве, рассчитываемое как `clusters` в степени `levels`, должно быть не более чем 1073741824; * произведение `vector_dimension` на `clusters` должно быть не более чем 4194304. {% note info %} Для векторных индексов параметры `vector_type` и `vector_dimension` можно не указывать, если таблица не пуста — они определяются автоматически по содержимому строк. Параметры `levels` и `clusters` также определяются автоматически, и для них таблица может быть пустой, но делать это крайне не рекоммендуется так как дефолтные значения в этом случае `levels`=1, `clusters`=2, гораздо лучше создавать индекс по таблице куда уже загруженны данные, чтобы значения могли правильно определиться. {% endnote %} Параметры, специфичные для полнотекстовых индексов: * общие параметры для всех полнотекстовых индексов: * `tokenizer` - тип токенизатора (`standard`, `whitespace` или `keyword`) * `use_filter_lowercase` - фильтр приведения к нижнему регистру (`true` или `false`) * `use_filter_length` - фильтр по длине токена (`true` или `false`); при значении `true` токены короче `filter_length_min` или длиннее `filter_length_max` не индексируются и не участвуют в поиске * `filter_length_min` - минимальная длина токена (положительное целое); применяется только при `use_filter_length=true` * `filter_length_max` - максимальная длина токена (положительное целое); применяется только при `use_filter_length=true` * `use_filter_snowball` - фильтр стемминга [Snowball](https://snowballstem.org/) (`true` или `false`) * `language` - язык для стеммера [Snowball](https://snowballstem.org/) (например, `english`, `russian`) * `use_filter_ngram` - фильтр [N-грамм](https://en.wikipedia.org/wiki/N-gram) (`true` или `false`) * `use_filter_edge_ngram` - фильтр краевых [N-грамм](https://en.wikipedia.org/wiki/N-gram) (`true` или `false`) * `filter_ngram_min_length` - минимальная длина N-граммы (положительное целое) * `filter_ngram_max_length` - максимальная длина N-граммы (положительное целое) ### Параметры локальных блум-индексов {#local-bloom} * `bloom_filter` * `false_positive_probability` — целевая [вероятность ложноположительного срабатывания](https://ru.wikipedia.org/wiki/Фильтр_Блума#Вероятность_ложных_срабатываний) фильтра: доля фрагментов, которые фильтр не отсечёт, хотя искомого значения в них нет (диапазон `(0, 1)`). Меньшее значение уменьшает число лишних чтений, но увеличивает размер индекса. * Если параметр не указан, для [строковых таблиц](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#row-oriented-table) используется `0.0001`, для [колоночных](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table) — `0.1`. Более строгий порог по умолчанию в строковых таблицах соответствует OLTP-сценарию точечных чтений; в колоночных — аналитическим сканам, где допустим больший компромисс между размером индекса и отсечением фрагментов. * Индексируемые колонки — типы YQL, для которых определено сравнение на равенство, кроме `Yson`, `Json` и `JsonDocument` (см. [операторы сравнения](https://ydb.tech/docs/ru/yql/reference/syntax/expressions.md?version=main#comparison-operators)). В колоночной таблице допускается одна колонка; в строковой — несколько. На строковых таблицах индексируемые колонки должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). * `bloom_ngram_filter` (колонки `String`, `Utf8`; только [колоночные таблицы](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table)) * `ngram_size` — размер n-граммы, целое число от `3` до `8` (по умолчанию `3`). * `false_positive_probability` — целевая [вероятность ложноположительного срабатывания](https://ru.wikipedia.org/wiki/Фильтр_Блума#Вероятность_ложных_срабатываний) (диапазон `(0, 1)`; по умолчанию `0.1`). * `case_sensitive` — учёт регистра при построении n-грамм: `true` или `false` (по умолчанию `true`). ### Параметры локального min_max-индекса {#local-min-max} У min_max-индекса нет специфичных параметров `WITH (...)`. ### Ограничения Операция `ADD INDEX` для создания глобальных вторичных (`GLOBAL`, `UNIQUE` и т.п.) и векторных индексов поддерживается только для строковых таблиц. Для [колоночных таблиц](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-oriented-tables) через `ADD INDEX` поддерживаются только локальные индексы: [блум-индекс](#local-bloom) и [min_max-индекс](#local-min-max). Особенности локальных блум-индексов: * Индекс всегда [локальный](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#local-index) (`LOCAL`); [глобального](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#secondary-index) варианта нет. * В запросах не используется синтаксис `VIEW ` (в отличие, например, от [полнотекстовых индексов](https://ydb.tech/docs/ru/dev/fulltext-indexes.md?version=main)). * Фильтр применяется при чтении только к тем фрагментам данных, для которых при записи или [слиянии порций](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#compaction) уже сохранён блок индекса, для остальных фрагментов пропуск по этому индексу не выполняется. * На [строковых таблицах](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#row-oriented-table) `bloom_filter` реализован как **префиксный фильтр Блума**: индексируемые колонки должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). Фильтр строится по этому префиксу ключа и ускоряет точечные чтения и сканы по диапазону, ограничивающие префикс. Два индекса `bloom_filter` с одинаковой длиной префикса не допускаются. {% note info "Ограничения" %} * Секции `COVER (...)` и дополнительные колонки индекса не поддерживаются. * Для колоночных таблиц индексируемая колонка должна быть одна. Для строковых таблиц допускается несколько индексируемых колонок. * Для строковых таблиц тип индекса `bloom_ngram_filter` не поддерживается. * На строковых таблицах индексируемые колонки `bloom_filter` должны образовывать левый префикс [первичного ключа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#primary-key). Наборы колонок, не являющиеся префиксом, отклоняются. * На строковых таблицах два индекса `bloom_filter` не могут иметь одинаковую длину префикса (один и тот же набор ведущих колонок первичного ключа). {% endnote %} Особенности локального min_max-индекса: * Индекс всегда [локальный](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#local-index) (`LOCAL`); [глобального](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#secondary-index) варианта нет. * В запросах не используется синтаксис `VIEW ` (в отличие, например, от [полнотекстовых индексов](https://ydb.tech/docs/ru/dev/fulltext-indexes.md?version=main)). * Фильтр применяется при чтении только к тем фрагментам данных, для которых при записи или [слиянии](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#compaction) уже вычислены и сохранены вместе с данными таблицы минимальное и максимальное значения индексируемой колонки; для остальных фрагментов пропуск по этому индексу не выполняется. {% note info "Ограничения" %} * Поддерживаются только для [колоночных таблиц](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#column-oriented-table). * В `ON (...)` должна быть указана ровно одна колонка. * `COVER (...)` и дополнительные колонки данных не поддерживаются. * Специфичные параметры `WITH (...)` не поддерживаются. * `ALTER INDEX` для min_max-индекса не поддерживается. * Колонки типов `Json` и `JsonDocument` не поддерживаются. {% endnote %} ### Примеры Вторичный индекс: ```yql ALTER TABLE `series` ADD INDEX `title_index` GLOBAL ON (`title`); ``` [Векторный индекс](https://ydb.tech/docs/ru/dev/vector-indexes.md?version=main): ```yql ALTER TABLE `series` ADD INDEX emb_cosine_idx GLOBAL SYNC USING vector_kmeans_tree ON (embedding) COVER (title) WITH ( distance="cosine", vector_type="float", vector_dimension=512 ); ``` Полнотекстовый индекс: ```yql ALTER TABLE `series` ADD INDEX ft_idx GLOBAL USING fulltext_plain ON (title) WITH (tokenizer=standard, use_filter_lowercase=true); ``` [JSON-индекс](https://ydb.tech/docs/ru/dev/json-indexes.md?version=main): ```yql ALTER TABLE `series` ADD INDEX json_idx GLOBAL USING json ON (metadata); ``` [Блум-индекс](https://ydb.tech/docs/ru/dev/bloom-skip-indexes.md?version=main): ```yql ALTER TABLE `/Root/Table` ADD INDEX idx_bloom LOCAL USING bloom_filter ON (resource_id) WITH (false_positive_probability = 0.01); ``` Блум n-граммный индекс: ```yql ALTER TABLE `/Root/Table` ADD INDEX idx_ngram LOCAL USING bloom_ngram_filter ON (message) WITH ( ngram_size = 3, false_positive_probability = 0.01, case_sensitive = true ); ``` min_max-индекс: ```yql ALTER TABLE `/Root/Table` ADD INDEX idx_created_at LOCAL USING min_max ON (created_at); ``` ## Изменение параметров индекса {#alter-index} Индексы имеют параметры, зависящие от типа, которые можно настраивать. Глобальные индексы, [синхронные](https://ydb.tech/docs/ru/concepts/query_execution/secondary_indexes.md?version=main#sync) или [асинхронные](https://ydb.tech/docs/ru/concepts/query_execution/secondary_indexes.md?version=main#async), реализованы в виде скрытых таблиц, и их параметры автоматического партиционирования и реплик можно регулировать так же, как и настройки обычных таблиц. {% note info %} В настоящее время задание настроек партиционирования вторичных индексов при создании индекса не поддерживается ни в операторе [`ALTER TABLE ADD INDEX`](#add-index), ни в операторе [`CREATE TABLE INDEX`](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/secondary_index.md?version=main). {% endnote %} ```yql ALTER TABLE ALTER INDEX SET ; ALTER TABLE ALTER INDEX SET ( = , ...); ``` * `` - имя таблицы, индекс которой нужно изменить. * `` - имя индекса, который нужно изменить. * `` - имя изменяемого параметра. Набор допустимых параметров зависит от типа индекса: * для глобальных вторичных индексов: * [AUTO_PARTITIONING_BY_SIZE](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#auto_partitioning_by_size) * [AUTO_PARTITIONING_BY_LOAD](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#auto_partitioning_by_load) * [AUTO_PARTITIONING_PARTITION_SIZE_MB](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#auto_partitioning_partition_size_mb) * [AUTO_PARTITIONING_MIN_PARTITIONS_COUNT](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#auto_partitioning_min_partitions_count) * [AUTO_PARTITIONING_MAX_PARTITIONS_COUNT](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#auto_partitioning_max_partitions_count) * [READ_REPLICAS_SETTINGS](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#read_only_replicas) * для локальных блум-индексов (см. [Параметры локальных блум-индексов](#local-bloom)): * `FALSE_POSITIVE_PROBABILITY` * `NGRAM_SIZE` и `CASE_SENSITIVE` (только для `bloom_ngram_filter`) * min_max-индекс не поддерживает `ALTER INDEX`. {% note info %} Операция `RESET` для `ALTER INDEX` не поддерживается. {% endnote %} * `` - новое значение параметра. Возможные значения включают: * `ENABLED` или `DISABLED` для параметров `AUTO_PARTITIONING_BY_SIZE` и `AUTO_PARTITIONING_BY_LOAD` * `"PER_AZ:"` или `"ANY_AZ:"` где `` — число реплик для `READ_REPLICAS_SETTINGS` * для остальных параметров — целое число типа `Uint64` * для `FALSE_POSITIVE_PROBABILITY` — число с плавающей точкой в диапазоне `(0, 1)`; меньшее значение обычно уменьшает число ложноположительных срабатываний, но увеличивает размер индекса * для `NGRAM_SIZE` — целое число в диапазоне от `3` до `8` (обычно рекомендуется начинать с `3`) * для `CASE_SENSITIVE` — `true` или `false` ### Пример Код из следующего примера включает автоматическое партиционирование по нагрузке для индекса с именем `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" ); ``` Для локальных блум-индексов можно также менять специфичные для них параметры, например: ```yql ALTER TABLE `/Root/Table` ALTER INDEX idx_ngram SET ( ngram_size = 4, false_positive_probability = 0.005, case_sensitive = false ); ``` ## Удаление индекса {#drop-index} `DROP INDEX` — удаляет индекс с указанным именем. Приведенный ниже код удалит индекс с именем `title_index`. ```yql ALTER TABLE `series` DROP INDEX `title_index`; ``` Также удалить индекс можно с помощью команды [table index](https://ydb.tech/docs/ru/reference/ydb-cli/commands/secondary_index.md?version=main#drop) YDB CLI. ## Переименование вторичного индекса {#rename-secondary-index} `RENAME INDEX` — переименовывает индекс с указанным именем. Если индекс с новым именем существует, будет возвращена ошибка. Возможность атомарной замены индекса под нагрузкой поддерживается командой [ydb table index rename](https://ydb.tech/docs/ru/reference/ydb-cli/commands/secondary_index.md?version=main#rename) YDB CLI и специализированными методами YDB SDK. Это относится к глобальным вторичным индексам (скрытая индексная таблица и режим `--replace`). Локальные блум-индексы к такой атомарной замене под нагрузкой не применимы. Пример переименования индекса: ```yql ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`; ```