> ## 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.

> Документация по ALTER

# ALTER

Большинство запросов `ALTER TABLE` изменяют настройки таблицы или данные:

| Модификатор                                                             |
| ----------------------------------------------------------------------- |
| [COLUMN](/docs/ru/reference/statements/alter/column)                         |
| [PARTITION](/docs/ru/reference/statements/alter/partition)                   |
| [DELETE](/docs/ru/reference/statements/alter/delete)                         |
| [UPDATE](/docs/ru/reference/statements/alter/update)                         |
| [ORDER BY](/docs/ru/reference/statements/alter/order-by)                     |
| [SAMPLE BY](/docs/ru/reference/statements/alter/sample-by)                   |
| [INDEX](/docs/ru/reference/statements/alter/skipping-index)                  |
| [PROJECTION](/docs/ru/reference/statements/alter/projection)                 |
| [CONSTRAINT](/docs/ru/reference/statements/alter/constraint)                 |
| [TTL](/docs/ru/reference/statements/alter/ttl)                               |
| [STATISTICS](/docs/ru/reference/statements/alter/statistics)                 |
| [SETTING](/docs/ru/reference/statements/alter/setting)                       |
| [APPLY DELETED MASK](/docs/ru/reference/statements/alter/apply-deleted-mask) |
| [APPLY PATCHES](/docs/ru/reference/statements/alter/apply-patches)           |

<Note>
  Большинство запросов `ALTER TABLE` поддерживаются только для таблиц [\*MergeTree](/docs/ru/reference/engines/table-engines/mergetree-family/index), [Merge](/docs/ru/reference/engines/table-engines/special/merge) и [Distributed](/docs/ru/reference/engines/table-engines/special/distributed).
</Note>

Эти операторы `ALTER` изменяют представления:

| Оператор                                                            | Описание                                                                      |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [ALTER TABLE ... MODIFY QUERY](/docs/ru/reference/statements/alter/view) | Изменяет структуру [materialized view](/docs/ru/reference/statements/create/view). |

Эти операторы `ALTER` изменяют сущности, связанные с ролевым управлением доступом:

| Оператор                                                            |
| ------------------------------------------------------------------- |
| [USER](/docs/ru/reference/statements/alter/user)                         |
| [ROLE](/docs/ru/reference/statements/alter/role)                         |
| [QUOTA](/docs/ru/reference/statements/alter/quota)                       |
| [ROW POLICY](/docs/ru/reference/statements/alter/row-policy)             |
| [MASKING POLICY](/docs/ru/reference/statements/alter/masking-policy)     |
| [SETTINGS PROFILE](/docs/ru/reference/statements/alter/settings-profile) |

| Оператор                                                                             | Описание                                                                                                     |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| [ALTER TABLE ... MODIFY COMMENT](/docs/ru/reference/statements/alter/comment)             | Добавляет, изменяет или удаляет комментарии к таблице вне зависимости от того, были ли они заданы ранее.     |
| [ALTER DATABASE ... MODIFY COMMENT](/docs/ru/reference/statements/alter/database-comment) | Добавляет, изменяет или удаляет комментарии к базе данных вне зависимости от того, были ли они заданы ранее. |
| [ALTER NAMED COLLECTION](/docs/ru/reference/statements/alter/named-collection)            | Изменяет [именованные коллекции](/docs/ru/concepts/features/configuration/server-config/named-collections).       |

<div id="mutations">
  ## Мутации
</div>

Запросы `ALTER`, предназначенные для изменения данных в таблице, реализованы с помощью механизма под названием «мутации», в частности [ALTER TABLE ... DELETE](/docs/ru/reference/statements/alter/delete) и [ALTER TABLE ... UPDATE](/docs/ru/reference/statements/alter/update). Это асинхронные фоновые процессы, похожие на слияния в таблицах [MergeTree](/docs/ru/reference/engines/table-engines/mergetree-family/index), которые создают новые «мутированные» версии частей.

Для таблиц `*MergeTree` мутации выполняются путем **перезаписи частей данных целиком**.
Атомарности здесь нет — части заменяются мутированными, как только они готовы, и запрос `SELECT`, который начал выполняться во время мутации, увидит данные из уже измененных частей вместе с данными из частей, которые еще не были изменены.

Мутации полностью упорядочены по порядку создания и применяются к каждой части именно в этом порядке. Кроме того, мутации частично упорядочены относительно запросов `INSERT INTO`: данные, вставленные в таблицу до отправки мутации, будут изменены, а данные, вставленные после этого, — нет. Обратите внимание, что мутации никак не блокируют вставки.

Запрос мутации возвращает результат сразу после добавления записи о мутации (в случае реплицируемых таблиц — в ZooKeeper, для нереплицируемых таблиц — в файловую систему). Сама мутация выполняется асинхронно с использованием настроек системного профиля. Для отслеживания прогресса мутаций можно использовать таблицу [`system.mutations`](/docs/ru/reference/system-tables/mutations). Успешно отправленная мутация продолжит выполняться, даже если серверы ClickHouse будут перезапущены. После отправки мутацию нельзя откатить, но, если она по какой-либо причине зависла, ее можно отменить запросом [`KILL MUTATION`](/docs/ru/reference/statements/kill#kill-mutation).

Записи о завершенных мутациях удаляются не сразу (количество сохраняемых записей определяется параметром движка хранения `finished_mutations_to_keep`). Более старые записи о мутациях удаляются.

<div id="synchronicity-of-alter-queries">
  ## Синхронность запросов `ALTER`
</div>

Для нереплицируемых таблиц все запросы `ALTER` выполняются синхронно. Для реплицируемых таблиц запрос лишь добавляет в `ZooKeeper` инструкции для соответствующих действий, а сами действия выполняются как можно скорее. Однако запрос может ждать завершения этих действий на всех репликах.

Для запросов `ALTER`, создающих мутации (например, `UPDATE`, `DELETE`, `MATERIALIZE INDEX`, `MATERIALIZE PROJECTION`, `MATERIALIZE COLUMN`, `APPLY DELETED MASK`, `APPLY PATCHES`, `CLEAR STATISTIC`, `MATERIALIZE STATISTIC` и другие), синхронность определяется настройкой [mutations\_sync](/docs/ru/reference/settings/session-settings/mutations#mutations_sync).

Для других запросов `ALTER`, которые изменяют только метаданные, можно использовать настройку [alter\_sync](/docs/ru/reference/settings/session-settings/alter#alter_sync), чтобы настроить ожидание.

С помощью настройки [replication\_wait\_for\_inactive\_replica\_timeout](/docs/ru/reference/settings/session-settings/other#replication_wait_for_inactive_replica_timeout) можно указать, как долго (в секундах) ждать, пока неактивные реплики выполнят все запросы `ALTER`.

<Note>
  Для всех запросов `ALTER`: если `alter_sync = 2` и некоторые реплики остаются неактивными дольше времени, указанного в настройке `replication_wait_for_inactive_replica_timeout`, генерируется исключение `UNFINISHED`.
</Note>

<div id="concurrent-alter-assignment-on-one-table">
  ### Одновременное назначение `ALTER` для одной таблицы
</div>

В реплицируемых таблицах быстрая последовательная отправка нескольких отдельных операторов `ALTER` для одной и той же таблицы может завершиться ошибкой `CANNOT_ASSIGN_ALTER` (код 517). В реплицируемом пути эта ошибка возникает, если реплика ещё не применила некоторые предыдущие `ALTER` (версия метаданных всё ещё отстаёт от общей версии метаданных — сервер может сообщить, что реплика «still not applied some of previous alters» или «Probably too many alters executing concurrently»). Это условие может сохраняться даже после того, как предыдущий `ALTER` уже был назначен. Это **общее условие одновременного выполнения `ALTER` метаданных / мутаций** — оно не ограничивается операторами, относящимися только к мутациям. Обычные одновременные изменения метаданных (`ADD` / `DROP` / `MODIFY` и аналогичные) могут вызывать тот же код, допускающий повторную попытку (см., например, путь повторной попытки в `tests/queries/0_stateless/03518_alter_logical_race.sh`).

Подходы, позволяющие избежать состояния гонки:

* Объединяйте независимые операции с метаданными в **один** `ALTER` с несколькими секциями, если это допускается грамматикой (например, несколько секций `ADD INDEX`).
* Выполняйте операторы `ALTER` последовательно и повторяйте попытку при коде 517, пока предыдущие `ALTER` не будут применены на реплике.
* Для `ALTER`, создающих мутации, дождитесь завершения предыдущей мутации, используя документированный наблюдаемый признак, например [`mutations_sync`](/docs/ru/reference/settings/session-settings/mutations#mutations_sync) или `is_done` в [`system.mutations`](/docs/ru/reference/system-tables/mutations), прежде чем отправлять следующий.

<div id="combining-materialize-index-clauses">
  ### Объединение секций `MATERIALIZE INDEX`
</div>

В одном операторе `ALTER` может содержаться несколько секций `MATERIALIZE INDEX`. Рассматриваемый в исходном коде случай — объединение нескольких секций `ADD INDEX` с `MATERIALIZE INDEX` для тех же новых индексов в одном операторе (см. `tests/queries/0_stateless/02911_add_index_and_materialize_index.sql`). Такая объединённая форма `ADD INDEX` + `MATERIALIZE INDEX` сочетает сегмент `AlterCommand` с сегментом `MutationCommand`, поэтому **`DatabaseReplicated` отклоняет её** с ошибкой `QUERY_IS_PROHIBITED` (`InterpreterAlterQuery::validateReplicatedDatabaseSegments`). Пример `02911` допустим для обычных баз данных (не `DatabaseReplicated`); в `DatabaseReplicated` выполняйте изменения метаданных и мутации материализации отдельными операторами.

В текущей реализации каждая секция `MATERIALIZE INDEX` разрешается относительно снимка метаданных таблицы при подготовке мутации, поэтому формы с несколькими секциями только `MATERIALIZE INDEX` для уже существующих индексов проходят тот же путь подготовки (только мутация, поэтому они остаются в пределах одного сегмента). Эта конкретная форма пока не покрыта отдельным stateless-тестом; до появления такого покрытия считайте её текущим поведением реализации, а не отдельно гарантированным контрактом.

Если требуется упорядоченное применение мутаций, можно по-прежнему выполнять по одному `MATERIALIZE INDEX` в каждом операторе и ждать завершения с помощью [`mutations_sync`](/docs/ru/reference/settings/session-settings/mutations#mutations_sync).

<div id="related-content">
  ## См. также
</div>

* Блог: [Обновления и удаления в ClickHouse](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)