Управление партициями и частями

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

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 — Полностью переписывает части в таблице (или в конкретной партиции).

DETACH PARTITION|PART

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 на всех репликах — все реплики сгенерируют исключение, кроме реплик-лидеров (поскольку допускается наличие нескольких лидеров).

DROP PARTITION|PART

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

DROP DETACHED PARTITION|PART

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

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

FORGET PARTITION

ALTER TABLE table_name FORGET PARTITION partition_expr

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

ALTER TABLE mt FORGET PARTITION '20201121';

ATTACH PARTITION|PART

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, чтобы добавить их в таблицу на всех репликах.

ATTACH PARTITION FROM

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, индексы и проекции должны быть идентичны. В противном случае целевая таблица может содержать надмножество индексов и проекций исходной таблицы.

REPLACE PARTITION

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, индексы и проекции должны быть идентичны. В противном случае целевая таблица может содержать надмножество индексов и проекций исходной таблицы.

MOVE PARTITION TO TABLE

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, индексы и проекции должны быть идентичны. В противном случае целевая таблица может иметь надмножество индексов и проекций исходной таблицы.

CLEAR COLUMN IN PARTITION

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

FREEZE PARTITION

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

Если вы используете набор дисков для хранения данных таблицы, каталог shadow/N появляется на каждом диске, и в нем хранятся части данных, соответствующие выражению PARTITION.

Внутри резервной копии создается такая же структура каталогов, как и внутри /var/lib/clickhouse/. Запрос выполняет chmod для всех файлов, запрещая запись в них. После создания резервной копии вы можете скопировать данные из /var/lib/clickhouse/shadow/ на удаленный сервер, а затем удалить их с локального сервера. Обратите внимание, что запрос ALTER t FREEZE PARTITION не реплицируется. Он создает локальную резервную копию только на локальном сервере. Запрос создает резервную копию практически мгновенно (но сначала дожидается завершения текущих запросов к соответствующей таблице). ALTER TABLE t FREEZE PARTITION копирует только данные, но не метаданные таблицы. Чтобы создать резервную копию метаданных таблицы, скопируйте файл /var/lib/clickhouse/metadata/database/table.sql. Чтобы восстановить данные из резервной копии, выполните следующие действия:

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

Восстановление из резервной копии не требует остановки сервера. Запрос обрабатывает части параллельно, количество потоков регулируется настройкой max_threads. Дополнительные сведения о резервном копировании и восстановлении данных см. в разделе “Backup and Restore in ClickHouse”.

UNFREEZE PARTITION

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

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

CLEAR INDEX IN PARTITION

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

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

FETCH PARTITION|PART

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

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

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

Например:

FETCH PARTITION

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

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, он не изменяет структуру таблицы и не сразу изменяет данные, доступные в таблице.

MOVE PARTITION|PART

Перемещает партиции или части данных на другой том или диск в таблицах с движком 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'

UPDATE IN PARTITION

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

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

DELETE IN PARTITION

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

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.

​DETACH PARTITION|PART

​DROP PARTITION|PART

​DROP DETACHED PARTITION|PART

​FORGET PARTITION

​ATTACH PARTITION|PART

​ATTACH PARTITION FROM

​REPLACE PARTITION

​MOVE PARTITION TO TABLE

​CLEAR COLUMN IN PARTITION

​FREEZE PARTITION

​UNFREEZE PARTITION

​CLEAR INDEX IN PARTITION

​FETCH PARTITION|PART

​MOVE PARTITION|PART

​UPDATE IN PARTITION

​Пример

​См. также

​DELETE IN PARTITION

​Пример

​ПЕРЕСОЗДАНИЕ ЧАСТЕЙ

​Пример

​См. также

​Как задать выражение партиционирования

DETACH PARTITION|PART

DROP PARTITION|PART

DROP DETACHED PARTITION|PART

FORGET PARTITION

ATTACH PARTITION|PART

ATTACH PARTITION FROM

REPLACE PARTITION

MOVE PARTITION TO TABLE

CLEAR COLUMN IN PARTITION

FREEZE PARTITION

UNFREEZE PARTITION

CLEAR INDEX IN PARTITION

FETCH PARTITION|PART

MOVE PARTITION|PART

UPDATE IN PARTITION

Пример

См. также

DELETE IN PARTITION

Пример

ПЕРЕСОЗДАНИЕ ЧАСТЕЙ

Пример

См. также

Как задать выражение партиционирования