Internals and Debugging

Internals & Failure

Go under the hood — the on-disk format, the execution engine, the source code — so you can debug the unfamiliar.

What this module covers

MergeTree on-disk part structure (column files, marks, checksums)
Compression internals
Query execution pipeline and processors
EXPLAIN (AST, SYNTAX, PLAN, PIPELINE, ESTIMATE)
ClickHouse source layout (src/Storages/MergeTree, src/Interpreters, src/Processors)
system.query_log, system.parts, system.mutations, system.merges
JOIN internals (hash join, memory limits)
Projections (selection logic)
Sparse primary index and granules (on-disk internals)
Data skipping indexes (on-disk internals)
Common failure modes — too many parts, memory limit exceeded, replication lag, merge starvation