Перейти к основному содержанию
Перейти к основному содержанию

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

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

  • 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 имя_таблицы [ON CLUSTER кластер] DETACH PARTITION|PART выражение_партиции

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

Пример:

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

Подробнее о задании выражения секционирования см. в разделе How to set the partition expression.

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

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

DROP PARTITION|PART​

ALTER TABLE имя_таблицы [ON CLUSTER кластер] DROP PARTITION|PART выражение_партиции

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

Подробнее о настройке выражения партиционирования см. в разделе How to set the partition expression.

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

Пример:

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

DROP DETACHED PARTITION|PART — удаление отсоединённого раздела/части​

ALTER TABLE имя_таблицы [ON CLUSTER кластер] DROP DETACHED PARTITION|PART ALL|выражение_партиции

Удаляет указанную часть или все части указанного раздела из detached. Подробнее о настройке выражения партиционирования см. в разделе How to set the partition expression.

FORGET PARTITION​

ALTER TABLE имя_таблицы FORGET PARTITION выражение_партиции

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

О настройке выражения секционирования читайте в разделе How to set the partition expression.

Пример:

ALTER TABLE mt FORGET PARTITION '20201121';

ATTACH PARTITION|PART​

ALTER TABLE имя_таблицы ATTACH PARTITION|PART выражение_партиции

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

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

ПЕРЕМЕЩЕНИЕ РАЗДЕЛА В ТАБЛИЦУ​

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 имя_таблицы [ON CLUSTER кластер] CLEAR COLUMN имя_столбца IN PARTITION выражение_партиции

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

Пример:

ALTER TABLE visits CLEAR COLUMN hour in PARTITION 201902

FREEZE PARTITION​

ALTER TABLE имя_таблицы [ON CLUSTER кластер] FREEZE [PARTITION выражение_партиции] [WITH NAME 'имя_бэкапа']

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

Примечание

Весь процесс создания резервной копии выполняется без остановки сервера.

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

В момент выполнения, для получения снимка данных, запрос создает жесткие ссылки (hardlinks) на данные таблицы. Жесткие ссылки размещаются в каталоге /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.

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

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

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

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

Для получения дополнительной информации о резервном копировании и восстановлении данных см. раздел Резервное копирование данных.

UNFREEZE PARTITION​

ALTER TABLE имя_таблицы [ON CLUSTER кластер] UNFREEZE [PARTITION 'выражение_партиции'] WITH NAME 'имя_бэкапа'

Удаляет замороженные (frozen) разделы с указанным именем на диске. Если клауза 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'

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

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

  1. Загружает партицию|кусок (partition|part) с указанного шарда. В 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;
  1. ПОЛУЧЕНИЕ ЧАСТИ
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 имя_таблицы [ON CLUSTER кластер] MOVE PARTITION|PART выражение_раздела TO DISK|VOLUME 'имя_диска'

Запрос 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;

См. также​

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;

См. также​

Как задать выражение разбиения (partition expression)​

Вы можете задать выражение разбиения в запросах 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'))).
  • С использованием идентификатора разбиения (partition ID). Partition ID — это строковый идентификатор разбиения (по возможности человекочитаемый), который используется как имя разбиения в файловой системе и в ZooKeeper. Partition 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.