| name | parts-diagnosis |
| description | Diagnose part/partition health of a MergeTree table — too many parts, slow/stuck merges, bad partition key. |
WHEN TO USE
The user is worried about a specific table's part/partition health: too many
parts, merge pressure, TOO_MANY_PARTS on insert, or a partition key that may be
too fine. Investigate that one table read-only, then give a concrete fix.
TOOLS TO RUN (in order)
get_table_ddl — engine (is it MergeTree-family?), PARTITION BY, ORDER BY.run_select_query on system.parts for active part count + sizes per partition: SELECT partition, count() AS parts, sum(rows) AS rows, sum(bytes_on_disk) AS bytes FROM system.parts WHERE database='<db>' AND table='<t>' AND active GROUP BY partition ORDER BY parts DESC. Many small active parts in a partition (e.g. >300) = merge pressure / tiny inserts; hundreds/thousands of partitions = key too fine.run_select_query on system.merges / system.mutations filtered to the table — are merges running or stuck?get_table_size — overall scale context.
REFERENCES TO LOAD
- the
system-table-reference reference skill — exact system.parts / system.merges / system.mutations columns.
- the
clickhouse-playbook reference skill — the mutations/merges + partition-cardinality guidance.
RULES
- Ground the cause in the real part counts/sizes you found — never invent numbers.
- Typical fixes: batch inserts (never 1 row per INSERT); coarser
PARTITION BY (e.g. toYYYYMM not toYYYYMMDD); let merges catch up or find why they're stuck (memory); the parts_to_throw_insert / max_parts_in_total context; when (and when NOT) to OPTIMIZE TABLE … FINAL.
- READ-ONLY; never append a
FORMAT clause. A human applies any change.
