> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по управлению индексами пропуска данных

# Управление индексами пропуска данных

Доступны следующие операции:

<div id="add-index">
  ## ADD INDEX
</div>

`ALTER TABLE [db.]table_name [ON CLUSTER cluster] ADD INDEX [IF NOT EXISTS] name expression TYPE type [GRANULARITY value] [FIRST|AFTER name]` — добавляет описание индекса в метаданные таблицы.

<div id="drop-index">
  ## DROP INDEX
</div>

`ALTER TABLE [db.]table_name [ON CLUSTER cluster] DROP INDEX [IF EXISTS] name` — удаляет описание индекса из метаданных таблицы и удаляет файлы индекса с диска. Реализовано как [мутация](/docs/ru/reference/statements/alter/index#mutations).

<div id="materialize-index">
  ## MATERIALIZE INDEX
</div>

`ALTER TABLE [db.]table_name [ON CLUSTER cluster] MATERIALIZE INDEX [IF EXISTS] name [IN PARTITION partition_name]` — перестраивает вторичный индекс `name` для указанной `partition_name`. Реализовано как [мутация](/docs/ru/reference/statements/alter/index#mutations). Если часть `IN PARTITION` опущена, индекс перестраивается для всех данных таблицы.

[`MATERIALIZE COLUMN`](/docs/ru/reference/statements/alter/column#materialize-column) не является полноценной заменой `MATERIALIZE INDEX`. Для частей формата **wide + full-storage** эта команда может перезаписывать значения столбцов, не обновляя **отдельные** файлы индексов пропуска данных (или текстовых индексов). Исключение составляют обычные индексы пропуска данных, хранящиеся в `skp_idx.packed`: их по-прежнему можно принудительно пересчитать для частей wide + full-storage (это небольшие подпотоки индексов пропуска данных при значении по умолчанию [`packed_skip_index_max_bytes`](/docs/ru/reference/settings/merge-tree-settings/other#packed_skip_index_max_bytes); полнотекстовые индексы так не упаковываются). Для **любой части, не относящейся к wide + full-storage** (включая **compact + full**, **compact + packed** и **wide + packed**) полная перезапись части может пересчитать уже существующие индексы — небольшие части обычно имеют формат compact, хотя по умолчанию используют полное хранилище части. Используйте `MATERIALIZE INDEX` для **детерминированного и немедленного** пересчёта, если индекс был добавлен в таблицу, уже содержащую данные (`ADD INDEX` изменяет только метаданные), а также после перезаписи столбцов в частях wide+full-storage, когда требуется немедленно перестроить отдельные файлы индексов. Новые индексы (включая текстовые) в исторических частях также могут быть материализованы при последующем слиянии, если включён параметр [`materialize_skip_indexes_on_merge`](/docs/ru/reference/settings/merge-tree-settings/materialize#materialize_skip_indexes_on_merge) и индекс не исключён с помощью [`exclude_materialize_skip_indexes_on_merge`](/docs/ru/reference/settings/merge-tree-settings/exclude#exclude_materialize_skip_indexes_on_merge); в противном случае они останутся нематериализованными до явного выполнения `MATERIALIZE INDEX`.

<div id="clear-index">
  ## CLEAR INDEX
</div>

`ALTER TABLE [db.]table_name [ON CLUSTER cluster] CLEAR INDEX [IF EXISTS] name [IN PARTITION partition_name]` — удаляет с диска файлы вторичного индекса, не удаляя его описание. Реализовано в виде [мутации](/docs/ru/reference/statements/alter/index#mutations).

Команды `ADD`, `DROP` и `CLEAR` считаются лёгковесными, поскольку они лишь изменяют метаданные или удаляют файлы.
Кроме того, они реплицируются, а метаданные индексов синхронизируются через ClickHouse Keeper или ZooKeeper.

<Note>
  Управление индексами поддерживается только для таблиц семейства [`*MergeTree`](/docs/ru/reference/engines/table-engines/mergetree-family/mergetree) (включая [реплицируемые](/docs/ru/reference/engines/table-engines/mergetree-family/replication) варианты).
</Note>

<div id="concurrent-alter-and-multi-clause-materialize-index">
  ## Параллельные `ALTER` и `MATERIALIZE INDEX` с несколькими секциями
</div>

В реплицируемых таблицах быстрое выполнение отдельных `ALTER` для одной таблицы может вызвать `CANNOT_ASSIGN_ALTER` (код 517), если предыдущие `ALTER` ещё не были применены на реплике (метаданные всё ещё отстают — это может сохраняться, даже если более ранний `ALTER` уже был назначен). Это общее состояние при параллельных `ALTER` метаданных / мутациях, а не только при мутациях; выполняйте операции последовательно или повторяйте попытки, дождитесь завершения предыдущих `ALTER`, создающих мутации, с помощью [`mutations_sync`](/docs/ru/reference/settings/session-settings/mutations#mutations_sync) / `is_done` в [`system.mutations`](/docs/ru/reference/system-tables/mutations), либо объединяйте независимые операции с метаданными в один `ALTER` с несколькими секциями, если это допускается грамматикой. См. [Синхронность запросов ALTER](/docs/ru/reference/statements/alter/index#synchronicity-of-alter-queries) и [Параллельное назначение ALTER](/docs/ru/reference/statements/alter/index#concurrent-alter-assignment-on-one-table).

В одном `ALTER` можно указать несколько секций `MATERIALIZE INDEX`. Рассматриваемый в кодовой базе случай — объединение нескольких секций `ADD INDEX` с `MATERIALIZE INDEX` для тех же новых индексов в одном операторе (`tests/queries/0_stateless/02911_add_index_and_materialize_index.sql`). Такая объединённая форма предназначена для обычных баз данных (не `DatabaseReplicated`) — `DatabaseReplicated` отклоняет смешанные секции `ADD INDEX` + `MATERIALIZE INDEX` с ошибкой `QUERY_IS_PROHIBITED`. Формы с несколькими секциями только `MATERIALIZE INDEX` для уже существующих индексов в текущей реализации используют тот же путь подготовки снимка метаданных, однако этот конкретный вариант пока не покрыт специализированным stateless-тестом — до появления такого покрытия считайте это поведением текущей реализации, а не отдельно гарантируемым контрактом. Для последовательного применения выполняйте по одному `MATERIALIZE INDEX` в каждом операторе и ожидайте с помощью [`mutations_sync`](/docs/ru/reference/settings/session-settings/mutations#mutations_sync).