ALTER TABLE ... PARTITION

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

• DETACH PARTITION|PART — Перемещает партицию или часть в каталог detached и удаляет сведения о ней.
• DROP PARTITION|PART — Удаляет партицию или часть.
• DROP DETACHED PARTITION|PART — Удаляет часть или все части партиции из detached.
• FORGET PARTITION — Удаляет метаданные партиции из ZooKeeper, если она пуста.
• ATTACH PARTITION|PART — Добавляет партицию или часть из каталога detached в таблицу.
• ATTACH PARTITION FROM — Копирует партицию данных из одной таблицы в другую и присоединяет её.
• REPLACE PARTITION — Копирует партицию данных из одной таблицы в другую и заменяет ею существующую.
• MOVE PARTITION TO TABLE — Перемещает партицию данных из одной таблицы в другую.
• CLEAR COLUMN IN PARTITION — Сбрасывает значение указанного столбца в партиции.
• CLEAR INDEX IN PARTITION — Сбрасывает указанный вторичный индекс в партиции.
• FREEZE PARTITION — Создаёт резервную копию партиции.
• UNFREEZE PARTITION — Удаляет резервную копию партиции.
• FETCH PARTITION|PART — Загружает часть или партицию с другого сервера.
• MOVE PARTITION|PART — Перемещает партицию/часть данных на другой диск или том.
• UPDATE IN PARTITION — Обновляет данные в партиции по условию.
• DELETE IN PARTITION — Удаляет данные в партиции по условию.
• REWRITE PARTS — Полностью выполняет пересоздание частей в таблице (или в конкретной партиции).

ALTER TABLE table_name [ON CLUSTER cluster] DETACH PARTITION|PART partition_expr

Перемещает все данные указанной партиции в каталог detached. Сервер забывает об отсоединённой партиции данных, как будто её не существует. Сервер не будет знать об этих данных, пока вы не выполните запрос ATTACH.

Пример:

ALTER TABLE mt DETACH PARTITION '2020-11-21';
ALTER TABLE mt DETACH PART 'all_2_2_0';

О том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

После выполнения запроса вы можете делать с данными в каталоге detached всё что угодно: удалить их из файловой системы или просто оставить там.

Этот запрос реплицируется — он перемещает данные в каталог detached на всех репликах. Обратите внимание, что выполнить этот запрос можно только на реплике-лидере. Чтобы узнать, является ли реплика лидером, выполните запрос SELECT к таблице system.replicas. Либо, что проще, выполните запрос DETACH на всех репликах — все реплики сгенерируют исключение, кроме реплик-лидеров (поскольку допускается наличие нескольких лидеров).

ALTER TABLE table_name [ON CLUSTER cluster] DROP PARTITION|PART partition_expr

Удаляет указанную партицию из таблицы. Этот запрос помечает партицию как неактивную и полностью удаляет данные примерно через 10 минут.

О том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

Запрос реплицируется — данные удаляются на всех репликах.

Пример:

ALTER TABLE mt DROP PARTITION '2020-11-21';
ALTER TABLE mt DROP PART 'all_4_4_0';

ALTER TABLE table_name [ON CLUSTER cluster] DROP DETACHED PARTITION|PART ALL|partition_expr

Удаляет указанную часть или все части указанной партиции из каталога detached. Подробнее о том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

ALTER TABLE table_name FORGET PARTITION partition_expr

Удаляет все метаданные о пустой партиции из ZooKeeper. Запрос завершится ошибкой, если партиция не пуста или неизвестна. Выполняйте это только для партиций, которые больше никогда не будут использоваться.

О том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

Пример:

ALTER TABLE mt FORGET PARTITION '20201121';

ALTER TABLE table_name ATTACH PARTITION|PART partition_expr

Добавляет данные в таблицу из каталога detached. Можно добавить данные для всей партиции или для отдельной её части. Примеры:

ALTER TABLE visits ATTACH PARTITION 201901;
ALTER TABLE visits ATTACH PART 201901_2_2_0;

Подробнее о том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

Этот запрос реплицируется. Реплика-инициатор проверяет, есть ли данные в каталоге detached. Если данные есть, запрос проверяет их целостность. Если всё в порядке, запрос добавляет данные в таблицу.

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

Вы можете поместить данные в каталог detached на одной реплике и использовать запрос ALTER ... ATTACH, чтобы добавить их в таблицу на всех репликах.

ALTER TABLE table2 [ON CLUSTER cluster] ATTACH PARTITION partition_expr FROM table1

Этот запрос копирует партицию данных из table1 в table2.

Обратите внимание:

• Данные не будут удалены ни из table1, ни из table2.
• table1 может быть временной таблицей.

Чтобы запрос выполнился успешно, должны выполняться следующие условия:

• Обе таблицы должны иметь одинаковую структуру.
• Обе таблицы должны иметь одинаковые ключ партиционирования, ключ ORDER BY и первичный ключ.
• Обе таблицы должны иметь одинаковую политику хранения.
• Целевая таблица должна включать все индексы и проекции из исходной таблицы. Если в целевой таблице включена настройка enforce_index_structure_match_on_partition_manipulation, индексы и проекции должны быть идентичны. В противном случае целевая таблица может содержать надмножество индексов и проекций исходной таблицы.

ALTER TABLE table2 [ON CLUSTER cluster] REPLACE PARTITION partition_expr FROM table1

Этот запрос копирует партицию данных из table1 в table2 и заменяет существующую партицию в table2. Операция атомарна.

Обратите внимание:

• Данные из table1 не удаляются.
• table1 может быть временной таблицей.

Чтобы запрос выполнился успешно, должны быть соблюдены следующие условия:

• Обе таблицы должны иметь одинаковую структуру.
• Обе таблицы должны иметь одинаковый ключ партиционирования, одинаковый ключ ORDER BY и одинаковый первичный ключ.
• Обе таблицы должны использовать одинаковую политику хранения.
• Целевая таблица должна включать все индексы и проекции исходной таблицы. Если в целевой таблице включена настройка enforce_index_structure_match_on_partition_manipulation, индексы и проекции должны быть идентичны. В противном случае целевая таблица может содержать надмножество индексов и проекций исходной таблицы.

ALTER TABLE table_source [ON CLUSTER cluster] MOVE PARTITION partition_expr TO TABLE table_dest

Этот запрос перемещает партицию данных из table_source в table_dest, удаляя данные из table_source.

Чтобы запрос выполнился успешно, должны быть соблюдены следующие условия:

• Обе таблицы должны иметь одинаковую структуру.
• Обе таблицы должны иметь одинаковый ключ партиционирования, одинаковый ключ ORDER BY и одинаковый первичный ключ.
• Обе таблицы должны иметь одинаковую политику хранения.
• Обе таблицы должны использовать движки одного семейства (реплицируемые или нереплицируемые).
• Целевая таблица должна включать все индексы и проекции из исходной таблицы. Если в целевой таблице включена настройка enforce_index_structure_match_on_partition_manipulation, индексы и проекции должны быть идентичны. В противном случае целевая таблица может иметь надмножество индексов и проекций исходной таблицы.

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR COLUMN column_name IN PARTITION partition_expr

Сбрасывает все значения в указанном столбце в партиции. Если при создании таблицы было задано выражение DEFAULT, этот запрос устанавливает для столбца указанное значение по умолчанию.

Пример:

ALTER TABLE visits CLEAR COLUMN hour in PARTITION 201902

ALTER TABLE table_name [ON CLUSTER cluster] FREEZE [PARTITION partition_expr] [WITH NAME 'backup_name']

Этот запрос создает локальную резервную копию указанной партиции. Если секция PARTITION не указана, запрос создает резервную копию всех партиций сразу.

Обратите внимание: для таблиц старого формата можно указать префикс имени партиции (например, 2019) — тогда запрос создаст резервную копию всех соответствующих партиций. О том, как задать выражение партиционирования, читайте в разделе Как задать выражение партиционирования.

Во время выполнения запроса для создания снимка данных создаются жесткие ссылки на данные таблицы. Жесткие ссылки размещаются в каталоге /var/lib/clickhouse/shadow/N/..., где:

• /var/lib/clickhouse/ — рабочий каталог ClickHouse, указанный в конфигурации.
• N — инкрементный номер резервной копии.
• если указан параметр WITH NAME, то вместо инкрементного номера используется значение параметра 'backup_name'.

Внутри резервной копии создается такая же структура каталогов, как и внутри /var/lib/clickhouse/. Запрос выполняет chmod для всех файлов, запрещая запись в них.

После создания резервной копии вы можете скопировать данные из /var/lib/clickhouse/shadow/ на удаленный сервер, а затем удалить их с локального сервера. Обратите внимание, что запрос ALTER t FREEZE PARTITION не реплицируется. Он создает локальную резервную копию только на локальном сервере.

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

ALTER TABLE t FREEZE PARTITION копирует только данные, но не метаданные таблицы. Чтобы создать резервную копию метаданных таблицы, скопируйте файл /var/lib/clickhouse/metadata/database/table.sql.

Чтобы восстановить данные из резервной копии, выполните следующие действия:

1. Создайте таблицу, если она не существует. Чтобы получить запрос, используйте файл .sql (замените в нем ATTACH на CREATE).
2. Скопируйте данные из каталога data/database/table/ внутри резервной копии в каталог /var/lib/clickhouse/data/database/table/detached/.
3. Выполните запросы ALTER TABLE t ATTACH PARTITION, чтобы добавить данные в таблицу.

Восстановление из резервной копии не требует остановки сервера.

Запрос обрабатывает части параллельно, количество потоков регулируется настройкой max_threads.

Дополнительные сведения о резервном копировании и восстановлении данных см. в разделе "Backup and Restore in ClickHouse".

ALTER TABLE table_name [ON CLUSTER cluster] UNFREEZE [PARTITION 'part_expr'] WITH NAME 'backup_name'

Удаляет с диска frozen-партиции с указанным именем. Если предложение PARTITION опущено, запрос удаляет резервные копии всех партиций сразу.

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR INDEX index_name IN PARTITION partition_expr

Этот запрос аналогичен CLEAR COLUMN, но сбрасывает индекс, а не данные столбца.

ALTER TABLE table_name [ON CLUSTER cluster] FETCH PARTITION|PART partition_expr FROM 'path-in-zookeeper'

Загружает партицию с другого сервера. Этот запрос работает только для реплицируемых таблиц.

Запрос выполняет следующие действия:

1. Загружает партицию|часть с указанного сегмента. В 'path-in-zookeeper' необходимо указать путь к сегменту в ZooKeeper.
2. Затем запрос помещает загруженные данные в каталог detached таблицы table_name. Используйте запрос ATTACH PARTITION|PART, чтобы добавить данные в таблицу.

Например:

1. FETCH PARTITION

ALTER TABLE users FETCH PARTITION 201902 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PARTITION 201902;

2. FETCH PART

ALTER TABLE users FETCH PART 201901_2_2_0 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PART 201901_2_2_0;

Обратите внимание:

• Запрос ALTER ... FETCH PARTITION|PART не реплицируется. Он помещает часть или партицию в каталог detached только на локальном сервере.
• Запрос ALTER TABLE ... ATTACH реплицируется. Он добавляет данные на все реплики. На одну из реплик данные добавляются из каталога detached, а на остальные — с соседних реплик.

Перед загрузкой система проверяет, существует ли партиция и совпадает ли структура таблицы. Наиболее подходящая реплика автоматически выбирается из числа исправных реплик.

Хотя запрос называется ALTER TABLE, он не изменяет структуру таблицы и не сразу изменяет данные, доступные в таблице.

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

ALTER TABLE table_name [ON CLUSTER cluster] MOVE PARTITION|PART partition_expr TO DISK|VOLUME 'disk_name'

Запрос ALTER TABLE t MOVE:

• Не реплицируется, поскольку у разных реплик могут быть разные политики хранения.
• Возвращает ошибку, если указанный диск или том не настроен. Запрос также возвращает ошибку, если условия перемещения данных, указанные в политике хранения, неприменимы.
• Может возвращать ошибку, если данные, которые нужно переместить, уже были перемещены фоновым процессом, параллельным запросом ALTER TABLE t MOVE или в результате фонового слияния данных. В этом случае пользователю не нужно выполнять никаких дополнительных действий.

Пример:

ALTER TABLE hits MOVE PART '20190301_14343_16206_438' TO VOLUME 'slow'
ALTER TABLE hits MOVE PARTITION '2019-09-01' TO DISK 'fast_ssd'

Изменяет данные в указанной партиции, которые соответствуют заданному выражению фильтрации. Реализовано как мутация.

Синтаксис:

ALTER TABLE [db.]table [ON CLUSTER cluster] UPDATE column1 = expr1 [, ...] [IN PARTITION partition_expr] WHERE filter_expr

-- использование имени партиции
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- использование идентификатора партиции
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

• UPDATE

Удаляет данные в указанной партиции, соответствующие заданному выражению фильтрации. Реализовано в виде мутации.

Синтаксис:

ALTER TABLE [db.]table [ON CLUSTER cluster] DELETE [IN PARTITION partition_expr] WHERE filter_expr

-- используя имя партиции
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- используя идентификатор партиции
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

Это полностью пересоздаст части с использованием всех новых настроек. Это оправданно, поскольку настройки на уровне таблицы, такие как use_const_adaptive_granularity, по умолчанию применяются только к новым частям.

ALTER TABLE mt REWRITE PARTS;
ALTER TABLE mt REWRITE PARTS IN PARTITION 2;

• DELETE

Вы можете задавать выражение партиционирования в запросах ALTER ... PARTITION разными способами:

• Как значение из столбца partition таблицы system.parts. Например, ALTER TABLE visits DETACH PARTITION 201901.
• С помощью ключевого слова ALL. Его можно использовать только с DROP/DETACH/ATTACH/ATTACH FROM. Например, ALTER TABLE visits ATTACH PARTITION ALL.
• Как кортеж выражений или констант, соответствующий (по типам) кортежу ключей партиционирования таблицы. Если ключ партиционирования состоит из одного элемента, выражение нужно обернуть в функцию tuple (...). Например, ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25'))).
• С помощью ID партиции. ID партиции — это строковый идентификатор партиции (по возможности человекочитаемый), который используется в качестве имени партиции в файловой системе и в ZooKeeper. ID партиции должен быть указан в операторе PARTITION ID, в одинарных кавычках. Например, ALTER TABLE visits DETACH PARTITION ID '201901'.
• В запросах ALTER ATTACH PART и DROP DETACHED PART для указания имени части используйте строковый литерал со значением из столбца name таблицы system.detached_parts. Например, ALTER TABLE visits ATTACH PART '201901_1_1_0'.

Использование кавычек при указании партиции зависит от типа выражения партиционирования. Например, для типа String его значение нужно указывать в кавычках ('). Для типов Date и Int* кавычки не нужны.

Все приведённые выше правила также применимы к запросу OPTIMIZE. Если при оптимизации непартиционированной таблицы нужно указать единственную партицию, задайте выражение PARTITION tuple(). Например:

OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;

IN PARTITION указывает партицию, к которой применяются выражения UPDATE или DELETE в запросе ALTER TABLE. Новые части создаются только для указанной партиции. Таким образом, IN PARTITION помогает снизить нагрузку, когда таблица разделена на множество партиций, а обновить данные нужно только точечно.

Примеры запросов ALTER ... PARTITION приведены в тестах 00502_custom_partitioning_local и 00502_custom_partitioning_replicated_zookeeper.