Docs: explain what SYSTEM STOP MERGES does not cover - #126337

Related: #91183

Changelog category (leave one):

• Documentation (changelog entry is not required)

What and why

The SYSTEM STOP MERGES section only says that DETACH / ATTACH restarts merges. Four other behaviours surprised us while writing a training lab, so this PR documents them in the documentation registration (src/Parsers/ParserSystemQuery.cpp). The generated region of docs/reference/statements/system.mdx is not edited by hand, following docs/reference/AGENTS.md.

1. OPTIMIZE TABLE (with or without FINAL) on a plain MergeTree table with stopped merges fails with Cancelled merging parts. (ABORTED). Source: StorageMergeTree::merge checks merges_blocker.isCancelledForPartition() before selecting parts.
2. SYSTEM STOP MERGES without a table name only locks the tables that exist at that moment. InterpreterSystemQuery::startStopActionInDatabase iterates over the existing tables. Tables created later still merge, which is what SYSTEM STOP MERGES not applying to newly created tables #91183 reports.
3. SYSTEM STOP MERGES db.t for a table that does not exist yet returns Ok. and has no effect on a table created later under that name. startStopAction uses tryGetTable and does nothing when the table is missing.
4. The locks live in memory in the ActionLocksManager, so merges run again after a server restart.

The text about OPTIMIZE only claims non-replicated MergeTree. ReplicatedMergeTree takes a different path (log entry plus replication queue), and I did not test it.

How it was checked

ClickHouse 26.8.7.19 (official build, clickhouse-common-static LTS tarball), single server in a Kubernetes pod, run on 2026-10-16 (UTC). Script excerpt and output:

-- A. table-level stop
CREATE TABLE default.t1 (x UInt32) ENGINE=MergeTree ORDER BY x
SYSTEM STOP MERGES default.t1
INSERT x3
OPTIMIZE TABLE default.t1 FINAL  -> Code: 236. DB::Exception: Cancelled merging parts. (ABORTED)
OPTIMIZE TABLE default.t1        -> Code: 236. DB::Exception: Cancelled merging parts. (ABORTED)
active parts: 3

-- B. global stop, then a new table
SYSTEM STOP MERGES
CREATE TABLE default.t2 ...; INSERT x3
OPTIMIZE TABLE default.t2 FINAL  -> Ok, active parts: 1
OPTIMIZE TABLE default.t1 FINAL  -> Code: 236 ... (ABORTED)   (existing table is still stopped)

-- C. stop by name before the table exists
SYSTEM START MERGES
SYSTEM STOP MERGES default.t3    -> Ok.
CREATE TABLE default.t3 ...; INSERT x3
OPTIMIZE TABLE default.t3 FINAL  -> Ok, active parts: 1

-- D. restart
SYSTEM STOP MERGES default.t1; INSERT x2
OPTIMIZE TABLE default.t1 FINAL  -> Code: 236 ... (ABORTED)
(restart clickhouse server)
OPTIMIZE TABLE default.t1 FINAL  -> Ok, active parts: 1

-- E. existing note, re-checked
SYSTEM STOP MERGES default.t2; INSERT x2
OPTIMIZE TABLE default.t2 FINAL  -> Code: 236 ... (ABORTED)
DETACH TABLE default.t2; ATTACH TABLE default.t2
OPTIMIZE TABLE default.t2 FINAL  -> Ok, active parts: 1

This change was drafted with AI assistance and reviewed by me.

🤖 Generated with Claude Code

Workflow [PR]
Sync PR [sync-upstream/pr/126337]

Version info

• Merged into: 26.11.1.1020-master (included in 26.11 and later)