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

Добавление индекса

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

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

• GLOBAL/LOCAL — глобальный или локальный индекс, в зависимости от типа индекса (<index_type>) может быть доступен только один из них:

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

• <index_name> — уникальное имя индекса, по которому будет возможно обращение к данным.

• SYNC/ASYNC — признак синхронности индекса.

  • SYNC - синхронный индекс. Значение по умолчанию.
  • ASYNC - асинхронный индекс.

• UNIQUE — признак уникального вторичного индекса. Уникальный индекс должен быть глобальным синхронным (GLOBAL UNIQUE SYNC) и не должен содержать конструкцию USING <index_type>.

• <index_type> - тип индекса, в настоящее время поддерживаются:

  • secondary — вторичный индекс. Для вторичных индексов доступен только режим GLOBAL. Это тип индекса по умолчанию.
  • vector_kmeans_tree — векторный индекс. Подробнее описан в разделе Векторный индекс.
  • fulltext_plain — базовый полнотекстовый индекс. Подробнее описан в Полнотекстовый индекс.
  • fulltext_relevance — полнотекстовый индекс со статистикой BM25 для расчёта релевантности. Подробнее описан в Полнотекстовый индекс.
  • json — JSON-индекс для ускорения предикатов JSON_EXISTS и JSON_VALUE по колонке типа Json или JsonDocument. Подробнее описан в JSON-индекс.
  • bloom_filter — локальный Блум-индекс. Доступен только LOCAL. См. ALTER TABLE ADD INDEX.
  • bloom_ngram_filter — локальный N-граммный Блум-индекс. Доступен только LOCAL. См. ALTER TABLE ADD INDEX.
  • min_max — локальный min/max-индекс. Доступен только LOCAL. См. ALTER TABLE ADD INDEX.

• <index_columns> — список имён колонок создаваемой таблицы через запятую, по которому определяется состав и порядок включения колонок в ключ индекса. Обязательно должен быть указан. Ключ индекса будет состоять из этих колонок с добавлением колонок первичного ключа таблицы.

• <cover_columns> — список имён колонок создаваемой таблицы через запятую, которые будут сохранены в индексе дополнительно к колонкам ключа индекса, давая возможность получить дополнительные данные без обращения за ними в таблицу. По умолчанию пуст.

• <parameter_name> и <parameter_value> — параметры индекса, специфичные для конкретного <index_type>. Некоторые параметры индекса нельзя задать при его создании. См. Изменение параметров индекса.

Также добавить вторичный индекс можно с помощью команды table index YDB CLI.

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

• parallel - максимальное число параллельных обработчиков на основе партиций, задействованных в построении индекса (целое число между 1 и MaxBuildIndexShardsInFlight из SchemeShardConfig).
  • Если параметр не указан, сейчас используется значение по умолчанию 32 или MaxBuildIndexShardsInFlight, если это значение меньше. MaxBuildIndexShardsInFlight по умолчанию равен 1000. В будущих версиях логика выбора параллелизма по умолчанию может быть изменена.
  • Вы можете установить меньший лимит, чтобы снизить влияние построения индекса на производительность базы данных.
  • Вы также можете установить больший лимит, чтобы ускорить построение индекса, если у вас достаточно аппаратных ресурсов.

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

• общие параметры для всех векторных индексов:
  • vector_dimension - размерность вектора эмбеддинга (значение от 1 до 16384);
  • vector_type - тип значений вектора (float, uint8 или int8);
  • distance - функция расстояния (cosine, manhattan или euclidean), взаимосключающий с similarity;
  • similarity - функция схожести (inner_product или cosine), взаимосключающий с distance;
• специфичные параметры для vector_kmeans_tree (подробнее о типе индекса):
  • clusters - количество центроидов для алгоритма k-means (значение от 2 до 2048);
  • levels - количество уровней в дереве (значение от 1 до 16);
  • overlap_clusters - число ближайших кластеров, в которые будет добавлен каждый вектор (по умолчанию 1);
  • adaptive_clusters - для индексов с фильтрацией автоматически выбирать количество кластеров для каждого значения фильтруемой колонки в зависимости от количества векторов у этого значения (true или false, по умолчанию false). Подробнее см. Адаптивное количество кластеров;
  • общее количество узлов в дереве, рассчитываемое как clusters в степени levels, должно быть не более чем 1073741824;
  • произведение vector_dimension на clusters должно быть не более чем 4194304.

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

• общие параметры для всех полнотекстовых индексов:
  • 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 (true или false)
  • language - язык для стеммера Snowball (например, english, russian)
  • use_filter_ngram - фильтр N-грамм (true или false)
  • use_filter_edge_ngram - фильтр краевых N-грамм (true или false)
  • filter_ngram_min_length - минимальная длина N-граммы (положительное целое)
  • filter_ngram_max_length - максимальная длина N-граммы (положительное целое)

Параметры локальных блум-индексов

• bloom_filter
  • false_positive_probability — целевая вероятность ложноположительного срабатывания фильтра: доля фрагментов, которые фильтр не отсечёт, хотя искомого значения в них нет (диапазон (0, 1)). Меньшее значение уменьшает число лишних чтений, но увеличивает размер индекса.
    • Если параметр не указан, для строковых таблиц используется 0.0001, для колоночных — 0.1. Более строгий порог по умолчанию в строковых таблицах соответствует OLTP-сценарию точечных чтений; в колоночных — аналитическим сканам, где допустим больший компромисс между размером индекса и отсечением фрагментов.
  • Индексируемые колонки — типы YQL, для которых определено сравнение на равенство, кроме Yson, Json и JsonDocument (см. операторы сравнения). В колоночной таблице допускается одна колонка; в строковой — несколько. На строковых таблицах индексируемые колонки должны образовывать левый префикс первичного ключа.
• bloom_ngram_filter (колонки String, Utf8; только колоночные таблицы)
  • ngram_size — размер n-граммы, целое число от 3 до 8 (по умолчанию 3).
  • false_positive_probability — целевая вероятность ложноположительного срабатывания (диапазон (0, 1); по умолчанию 0.1).
  • case_sensitive — учёт регистра при построении n-грамм: true или false (по умолчанию true).

Параметры локального min_max-индекса

У min_max-индекса нет специфичных параметров WITH (...).

Ограничения

Операция ADD INDEX для создания глобальных вторичных (GLOBAL, UNIQUE и т.п.) и векторных индексов поддерживается только для строковых таблиц. Для колоночных таблиц через ADD INDEX поддерживаются только локальные индексы: блум-индекс и min_max-индекс.

Особенности локальных блум-индексов:

• Индекс всегда локальный (LOCAL); глобального варианта нет.
• В запросах не используется синтаксис VIEW <index> (в отличие, например, от полнотекстовых индексов).
• Фильтр применяется при чтении только к тем фрагментам данных, для которых при записи или слиянии порций уже сохранён блок индекса, для остальных фрагментов пропуск по этому индексу не выполняется.
• На строковых таблицах bloom_filter реализован как префиксный фильтр Блума: индексируемые колонки должны образовывать левый префикс первичного ключа. Фильтр строится по этому префиксу ключа и ускоряет точечные чтения и сканы по диапазону, ограничивающие префикс. Два индекса bloom_filter с одинаковой длиной префикса не допускаются.

Особенности локального min_max-индекса:

• Индекс всегда локальный (LOCAL); глобального варианта нет.
• В запросах не используется синтаксис VIEW <index> (в отличие, например, от полнотекстовых индексов).
• Фильтр применяется при чтении только к тем фрагментам данных, для которых при записи или слиянии уже вычислены и сохранены вместе с данными таблицы минимальное и максимальное значения индексируемой колонки; для остальных фрагментов пропуск по этому индексу не выполняется.

Примеры

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

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

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

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
  );

Полнотекстовый индекс:

ALTER TABLE `series`
  ADD INDEX ft_idx GLOBAL USING fulltext_plain
  ON (title)
  WITH (tokenizer=standard, use_filter_lowercase=true);

JSON-индекс:

ALTER TABLE `series`
  ADD INDEX json_idx GLOBAL USING json
  ON (metadata);

Блум-индекс:

ALTER TABLE `/Root/Table`
  ADD INDEX idx_bloom LOCAL USING bloom_filter
  ON (resource_id)
  WITH (false_positive_probability = 0.01);

Блум n-граммный индекс:

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-индекс:

ALTER TABLE `/Root/Table`
  ADD INDEX idx_created_at LOCAL USING min_max
  ON (created_at);

Изменение параметров индекса

Индексы имеют параметры, зависящие от типа, которые можно настраивать. Глобальные индексы, синхронные или асинхронные, реализованы в виде скрытых таблиц, и их параметры автоматического партиционирования и реплик можно регулировать так же, как и настройки обычных таблиц.

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
    • AUTO_PARTITIONING_BY_LOAD
    • AUTO_PARTITIONING_PARTITION_SIZE_MB
    • AUTO_PARTITIONING_MIN_PARTITIONS_COUNT
    • AUTO_PARTITIONING_MAX_PARTITIONS_COUNT
    • READ_REPLICAS_SETTINGS

  • для локальных блум-индексов (см. Параметры локальных блум-индексов):

    • FALSE_POSITIVE_PROBABILITY
    • NGRAM_SIZE и CASE_SENSITIVE (только для bloom_ngram_filter)

  • min_max-индекс не поддерживает ALTER INDEX.

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

  • ENABLED или DISABLED для параметров AUTO_PARTITIONING_BY_SIZE и AUTO_PARTITIONING_BY_LOAD
  • "PER_AZ:<count>" или "ANY_AZ:<count>" где <count> — число реплик для READ_REPLICAS_SETTINGS
  • для остальных параметров — целое число типа Uint64
  • для FALSE_POSITIVE_PROBABILITY — число с плавающей точкой в диапазоне (0, 1); меньшее значение обычно уменьшает число ложноположительных срабатываний, но увеличивает размер индекса
  • для NGRAM_SIZE — целое число в диапазоне от 3 до 8 (обычно рекомендуется начинать с 3)
  • для CASE_SENSITIVE — true или false

Пример

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

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"
);

Для локальных блум-индексов можно также менять специфичные для них параметры, например:

ALTER TABLE `/Root/Table` ALTER INDEX idx_ngram SET (
    ngram_size = 4,
    false_positive_probability = 0.005,
    case_sensitive = false
);

Удаление индекса

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

ALTER TABLE `series` DROP INDEX `title_index`;

Также удалить индекс можно с помощью команды table index YDB CLI.

Переименование вторичного индекса

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

Возможность атомарной замены индекса под нагрузкой поддерживается командой ydb table index rename YDB CLI и специализированными методами YDB SDK.

Это относится к глобальным вторичным индексам (скрытая индексная таблица и режим --replace). Локальные блум-индексы к такой атомарной замене под нагрузкой не применимы.

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

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