clickhouse/clickhouse

Query pipeline

This subsystem turns a SQL string into a stream of column chunks. It spans five directories under src/:

Directory	Stage	Page
`src/Parsers/`	SQL → AST	Parsers
`src/Analyzer/`	AST → `QueryTree`	Analyzer
`src/Planner/`	`QueryTree` → `QueryPlan`	Planner
`src/Interpreters/`	DDL, joins, aggregation, context, the legacy interpreter	Interpreters
`src/Processors/` + `src/QueryPipeline/`	The executor	Processors

graph LR
    SQL[SQL string] --> Parsers
    Parsers[Parsers<br/>AST] --> Analyzer
    Analyzer[Analyzer<br/>QueryTree] --> Planner
    Planner[Planner<br/>QueryPlan] --> Pipeline
    Pipeline[QueryPipeline<br/>Processor graph] --> Exec
    Exec[PipelineExecutor<br/>thread pool] --> Out[Chunk stream]
    Interp[Interpreters<br/>DDL + helpers] -.shared services.- Analyzer
    Interp -.shared services.- Planner
    Interp -.shared services.- Pipeline

Why the split

Historically ClickHouse went straight from AST to execution inside InterpreterSelectQuery. That worked but accumulated awkward edge cases in name resolution, subqueries, and view rewrites. In 2022 the project introduced a typed intermediate representation — the QueryTree — and a dedicated Planner. Both paths still exist; the analyzer is the default (enable_analyzer=1) and the legacy interpreter still handles a few corners and DDL queries.

Data exchange

An AST is a pointer-rich tree with no types attached. See src/Parsers/IAST.h.
A QueryTree is a typed, semantically-resolved tree. See src/Analyzer/IQueryTreeNode.h.
A QueryPlan is a tree of logical steps. See src/Processors/QueryPlan/IQueryPlanStep.h.
A QueryPipeline is a graph of physical processors. See src/QueryPipeline/QueryPipeline.h.

Every transition is in principle independent: you can stop after parsing (EXPLAIN AST), after analysis (EXPLAIN QUERY TREE), after planning (EXPLAIN PLAN), or after pipeline construction (EXPLAIN PIPELINE).

Why the split

Data exchange

Recommended reading order

Related pages