SYSTEM-команды: управление сервером

SYSTEM-команды — административный интерфейс ClickHouse: завершение зависших запросов, принудительный сброс логов, очистка кешей, синхронизация реплик. Большинство из них требует привилегии SYSTEM или специфической привилегии (например, KILL QUERY). На кластере каждая команда поддерживает суффикс ON CLUSTER cluster_name.

KILL QUERY: завершение запроса

Используется для принудительного завершения зависшего или слишком долго выполняющегося запроса.

Синтаксис

-- Завершить запрос по query_id (асинхронно — немедленный возврат)
KILL QUERY WHERE query_id = 'abc123-def456-ghi789' ASYNC;

-- Завершить запрос синхронно (ждать фактического завершения)
KILL QUERY WHERE query_id = 'abc123-def456-ghi789' SYNC;

-- Завершить все запросы конкретного пользователя
KILL QUERY WHERE user = 'analyst_user' ASYNC;

Получить query_id

-- Найти query_id зависшего запроса
SELECT query_id, elapsed, user, substring(query, 1, 100)
FROM system.processes
WHERE elapsed > 30
ORDER BY elapsed DESC
FORMAT PrettyCompact;

ON CLUSTER вариант

-- Убить запрос на всех узлах кластера
KILL QUERY WHERE query_id = 'abc123-def456-ghi789' ASYNC ON CLUSTER '{cluster}';

KILL MUTATION: остановка мутации

Мутации (ALTER TABLE ... UPDATE/DELETE) выполняются в фоне и могут занимать часы на больших таблицах. Если мутация запущена по ошибке или застряла — используйте KILL MUTATION.

-- Найти мутацию для отмены
SELECT database, table, mutation_id, command, parts_to_do
FROM system.mutations
WHERE is_done = 0
FORMAT PrettyCompact;

-- Остановить конкретную мутацию
KILL MUTATION WHERE database = 'default'
  AND table = 'events'
  AND mutation_id = '0000000003';

После KILL MUTATION мутация получает статус is_done = 1 с latest_fail_reason = 'killed'. Уже переписанные части остаются с изменениями — откат не выполняется автоматически.

ON CLUSTER вариант

-- Остановить мутацию на всех репликах
KILL MUTATION WHERE database = 'default'
  AND table = 'events'
  AND mutation_id = '0000000003'
  ON CLUSTER '{cluster}';

SYSTEM FLUSH LOGS: принудительный сброс

По умолчанию system.query_log, system.part_log и другие log-таблицы буферизируют записи в памяти и сбрасывают их каждые несколько секунд. FLUSH LOGS выполняет немедленный сброс.

-- Принудительно записать все буферизированные данные в log-таблицы
SYSTEM FLUSH LOGS;

Полезно перед диагностическим запросом к system.query_log — без flush недавние записи могут отсутствовать.

-- Паттерн: flush перед диагностикой
SYSTEM FLUSH LOGS;
SELECT query_id, formatReadableSize(memory_usage)
FROM system.query_log
WHERE type = 'QueryFinish'
  AND event_time >= now() - INTERVAL 5 MINUTE
ORDER BY memory_usage DESC
LIMIT 5
FORMAT PrettyCompact;

SYSTEM RELOAD DICTIONARIES: перезагрузка словарей

Принудительная перезагрузка всех словарей (dictionary) без перезапуска сервера. Используется после обновления источника данных словаря.

-- Перезагрузить все словари
SYSTEM RELOAD DICTIONARIES;

-- Перезагрузить конкретный словарь
SYSTEM RELOAD DICTIONARY default.country_codes;

Состояние словарей можно проверить через system.dictionaries:

SELECT name, status, last_successful_update_time
FROM system.dictionaries
ORDER BY name
FORMAT PrettyCompact;

SYSTEM DROP CACHES: очистка кешей

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

Mark Cache

Кеш меток (mark) ускоряет поиск по индексу. Занимает значительный объём RAM на больших таблицах.

-- Очистить кеш меток
SYSTEM DROP MARK CACHE;

Uncompressed Cache

Кеш несжатых данных (декомпрессированных блоков). Ускоряет повторное чтение тех же данных.

-- Очистить кеш несжатых данных
SYSTEM DROP UNCOMPRESSED CACHE;

Compiled Expression Cache

Кеш скомпилированных выражений (JIT-компиляция запросов).

-- Очистить кеш скомпилированных выражений
SYSTEM DROP COMPILED EXPRESSION CACHE;

ON CLUSTER вариант

-- Очистить кеш на всех узлах кластера
SYSTEM DROP MARK CACHE ON CLUSTER '{cluster}';

SYSTEM SYNC REPLICA: синхронизация реплики

Ждёт, пока реплика применит все ожидающие операции из очереди репликации. Полезно перед выполнением операций, требующих актуальных данных, или перед переключением трафика на реплику.

-- Дождаться применения всех ожидающих операций на реплике
SYSTEM SYNC REPLICA default.events;

-- С таймаутом (секунды)
SYSTEM SYNC REPLICA default.events STRICT;

Статус до и после:

-- Проверить очередь репликации
SELECT
    absolute_delay,
    queue_size,
    last_queue_update
FROM system.replicas
WHERE table = 'events'
FORMAT PrettyCompact;

Сводная таблица SYSTEM-команд

Ключевые выводы

1. KILL QUERY ASYNC — предпочтительный вариант для production. SYNC блокирует сессию до фактического завершения, что неудобно для длительных запросов.
2. SYSTEM FLUSH LOGS нужно вызывать перед диагностическими запросами к system.query_log — буферизированные записи могут быть ещё не сброшены.
3. KILL MUTATION не откатывает уже выполненные изменения. Если мутация частично применена — часть данных останется изменённой.
4. SYSTEM DROP MARK CACHE снижает производительность следующих запросов. Используйте только для диагностики или при явной необходимости освободить RAM.
5. Все SYSTEM-команды поддерживают ON CLUSTER — это позволяет выполнять административные операции на всех узлах кластера одной командой.