Optimizer on Opensource internals

ClickHouse Searches Join Orders with Dynamic Programming

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: Every DP algorithm here is the same three lines: enumerate splits of a relation set, cost each split with the NDV model, and keep the cheapest plan per relation set in a memo keyed by a bitmask. They differ in which splits they enumerate: DPsize enumerates all of them, DPhyp enumerates only connected ones, DPsub enumerates connected components and understands outer joins.

The previous article in this series explained the graph and the greedy search. The greedy search is O(N²) per step and gets stuck in local minima: it picks the cheapest pair now, and it may turn out that a different first pair would have been much better overall.

The principled fix is Bellman’s optimality principle applied to join trees:

If you know the best plan for every subset of relations, you can compute the best plan for any larger subset by trying every way of splitting it in two.

The catch is the state space. A plan is identified by the set of relations it covers, so the memo is a map from subsets to plans. For N relations there are 2^N subsets, and each one may be split in 2^(N-1) ways — for N=10 that is 2^10 · 2^9 ≈ 500 000 candidate evaluations, and for N=15 it is 2^28 ≈ 268 million. A naive implementation is not a query planner, it is a denial of service.

ClickHouse implements three variants that all share the same memo and cost model, and differ only in what they enumerate.

The memo

The memo is a BitSet → entry map:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:11
using PlanMemo = std::unordered_map<BitSet, DPJoinEntryPtr>;

The key is a BitSet — a wrapper over boost::dynamic_bitset — so a relation set is a machine word (or a few), and the map lookup is a hash of the bits.

The value is a DPJoinEntry: a node of the join tree being built, carrying its relation set, its two children, its cost, its selectivity, and its estimated output size.

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.h:32
struct DPJoinEntry
{
 BitSet relations;

 DPJoinEntryPtr left;
 DPJoinEntryPtr right;

 double cost = 0.0;
 /// NDV-based selectivity of the join predicates, see `SelectivityEstimate::reported_value`; reported by `EXPLAIN` as `estimated (NDV)`.
 double selectivity = 0.0;
 std::optional<UInt64> estimated_rows = {};
 std::unordered_map<String, ColumnStats> column_stats = {};

Every candidate evaluation goes through evaluateJoin, and it is where the “keep the cheapest” rule lives:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDP.cpp:42
 auto selectivity = computeSelectivity(query_graph, dp_table, expression_selectivity, predicates, left->relations, right->relations);
 auto new_cost = computeJoinCost(left, right, selectivity);

 const BitSet combined_rels = left->relations | right->relations;
 auto current_best = dp_table.find(combined_rels);
 if (current_best != dp_table.end() && new_cost >= current_best->second->cost)
 return nullptr;

Note the early exit: if the memo already holds a plan for left ∪ right that is at least as cheap, the candidate is discarded. This is what makes the whole thing a dynamic program rather than an exhaustive search — and it is also the reason the memo must be keyed by the relation set alone, with no other state.

There is one subtlety in the kind of the join. If the two sides are connected only transitively (through an equivalence class), the join is an inner join even though no predicate directly connects them; the predicate is synthesised later:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDP.cpp:50
 /// Transitively connected pairs are inner joins; their predicate is synthesized later.
 bool connected = !predicates.empty()
 || query_graph.areTransitivelyConnected(left->relations, right->relations);
 auto effective_kind = (connected && join_kind == JoinKind::Cross) ? JoinKind::Inner : join_kind;
 auto cardinality = estimateJoinCardinality(left, right, selectivity, effective_kind);

DPsize: enumerate everything

DPsize is the textbook bottom-up DP. It builds components in increasing size and, for each size, tries every way of splitting a component into two smaller ones:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:59
 /// Components by size (index 0 is not used that why the size is N+1)
 std::vector<std::unordered_map<BitSet, DPJoinEntryPtr>> components(total_relations_count + 1);

and the enumeration:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:76
 /// Iteratively build components of size from 2 to N
 for (size_t component_size = 2; component_size <= total_relations_count; ++component_size)
 {
 for (size_t smaller_component_size = 1; smaller_component_size <= component_size / 2; ++smaller_component_size)
 {
 const size_t bigger_component_size = component_size - smaller_component_size;

 for (const auto & [_, right] : components[smaller_component_size])
 {
 for (const auto & [_, left] : components[bigger_component_size])
 {
 /// Do components overlap?
 if (left->relations & right->relations)
 continue;

 /// If both components are of the same size then check each pair just once, not twice
 if (smaller_component_size == bigger_component_size && *left->relations.begin() > *right->relations.begin())
 continue;

The two continues are the standard symmetry eliminations: a split is unordered, so smaller/bigger is enough, and equal-size splits are checked once.

The plan is then gated on connectivity, because a plan that joins two unrelated components is a cross product and the optimizer does not want to invent one:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:158
 bool connected = !edge.empty()
 || query_graph.areTransitivelyConnected(left->relations, right->relations);

 LOG_TEST(log, "Considering join between {} and {}, predicates count: {}, connected: {}",
 left->dump(), right->dump(), edge.size(), connected);

 if (!connected)
 continue;

And DPsize is inner-join only:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:110
 /// FIXME: Restrict to Inner joins for now because isValidJoinOrder seems to not handle non-Inner joins with swapped inputs correctly
 if (*join_kind != JoinKind::Inner)
 continue;

which is why the setting’s documentation says “currently only for Inner joins”.

DPhyp: enumerate only connected subsets

DPsize’s problem is that it enumerates disconnected intermediate results. On a sparse join graph — say 10 tables where each table joins to two others — most subsets of size 5 are disconnected, and DPsize pays for every one of them before throwing them away.

DPhyp (“Dynamic Programming Strikes Back”, Moerkotte & Neumann, SIGMOD 2008) fixes this by working on a hypergraph and enumerating only connected subgraphs (CSG) and their complements (CMP).

The hyperedge representation is a natural fit for SQL, because a join predicate may reference more than two relations:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:63
 /** A hyperedge in the join graph connecting a set of left relations to a set of right relations.
 * For simple binary predicates (A.x = B.y), |left| = |right| = 1.
 * For complex predicates (A.x = B.y + C.z), left and/or right may span multiple relations.
 */
 struct Hyperedge
 {
 BitSet left;
 BitSet right;
 };

A non-binary predicate is represented with the same set on both sides, which is a neat trick:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:294
/// Non-binary predicates like `f(A,B,C) = const` are represented as L={A,B,C}, R={A,B,C}

The neighbourhood function is what makes the enumeration connected-only: a relation is a neighbour of a set if some hyperedge has one side fully inside the set and the other side outside it.

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:317
 if (isSubsetOf(edge.left, node_set))
 neighbors |= edge.right;
 if (isSubsetOf(edge.right, node_set))
 neighbors |= edge.left;

The enumeration is four functions, transcribed from the paper:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:357
/// The four functions below implement the core DPhyp enumeration from
/// "Dynamic Programming Strikes Back" (Moerkotte & Neumann, SIGMOD 2008), Section 3.
///
/// `emitCsg` (paper: EmitCsg, Sec 3.3) -- given a connected subgraph S1, generates all
/// complement seeds S2 = {v} from the neighborhood and extends them via `enumerateCmpRec`.
/// `enumerateCmpRec` (paper: EnumerateCmpRec, Sec 3.4) -- recursively extends complement S2
/// by adding neighboring nodes, emitting each valid csg-cmp pair.
/// `enumerateCsgRec` (paper: EnumerateCsgRec, Sec 3.2) -- recursively extends the primary
/// connected subgraph S1 by adding neighboring nodes.
/// `emitCsgCmp` (paper: EmitCsgCmp, Sec 3.5) -- evaluates a (S1, S2) pair for plan construction.

The cleverest part is the exclusion set, which is what stops the enumeration from producing every pair twice:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:421
/// Generate all complement seeds for a given connected subgraph S1.
/// Seeds are single neighbor nodes, processed in descending index order. Each processed seed is
/// added to the exclusion passed to later seeds, so a complement spanning several neighbors is grown
/// from only one of them and each (S1, S2) pair is enumerated exactly once.
///
/// `exclusion` (paper: X) = S1 | B_min(S1), where B_min(S1) = {v : v < min(S1)}.
/// B_min excludes all relations ordered before the smallest relation in S1.
/// This is the key mechanism that prevents generating symmetric pairs:
/// the complement can only contain relations ordered after the CSG's minimum.

The main loop seeds each single relation and grows:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:540
 /// Main DPhyp loop (paper: Solve, Sec 3.1).
 /// Seed with each single-relation CSG in descending index order.
 /// For each seed {v}, `emitCsg` finds complements (the other side of the join),
 /// and `enumerateCsgRec` grows {v} into larger connected subgraphs.
 /// The exclusion set B_v = {w : w < v} | {v} ensures each unordered (S1, S2) pair
 /// is considered exactly once (the side with the smaller min-index is always S1).

DPhyp has two hard limits. The subset enumeration uses a 64-bit bitmask, so it gives up at 64 relations:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:509
 /// DPhyp's subset enumeration uses a 64-bit bitmask, so it cannot handle neighborhoods
 /// larger than 63 relations. Bail out gracefully so the fallback algorithm chain can continue.
 if (num_relations >= 64)

and it cannot handle disconnected graphs at all, because it never considers cross products:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPHyp.cpp:573
 /// DPhyp cannot produce a plan for disconnected graphs (no cross products).
 /// The caller's fallback chain (e.g. dphyp,greedy) handles this.
 LOG_TRACE(log, "Failed to find best plan using DPhyp algorithm");
 return nullptr;

DPsub: connected components, and outer joins

DPsub is the algorithm from the “Building Query Compilers” paper, and it is the one that understands outer joins. Its state is a connected component of the join graph rather than an arbitrary subset:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:553
/** Implements the `Dpsub` bottom-up dynamic programming algorithm for optimal bushy join tree generation.
* This algorithm constructs optimal join trees by iterating over subsets of the relations in an ascending order
* based on an integer bitmask (from 1 to 2^n - 2). This ordering ensures that for any relation subset S,
* the best plans for all its proper sub-plans (subsets S1 ⊂ S) have already been computed, thereby adhering to
* Bellman's optimality principle.
* This methodical evaluation of all connected subsets results in the creation of the best plan for each.
* The final answer is the optimal plan for the complete set of relations.

Its state fits in a UInt32:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:571
 const size_t n = query_graph.relation_stats.size();
 using Bitvector = UInt32; // choose UInt64 or even UInt128 for larger sets
 // A budget cap on nr. of connected components considered by DPsub to avoid excessive optimization time on large join graphs.
 // This budget cap is obtained from empirical testing using different queries and join graphs.
 static constexpr UInt32 max_nr_ccps = 50'000;

— and if there are more relations than bits, it declines:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:577
 if (n >= std::numeric_limits<Bitvector>::digits)
 {
 LOG_TRACE(log,
 "Number of relations {} exceeds the DP threshold {}, skipping DP optimization invoking greedy algorithm",
 n, std::numeric_limits<Bitvector>::digits);
 return nullptr;
 }

Outer joins in DPsub

The reason DPsub exists separately is that outer joins are not freely reorderable, and the rule is fiddly. DPsub encodes it as a required set per relation: the null-supplying relation of an outer join may only be joined against a side that contains every relation its ON clause mentions.

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:280
 auto check = [&](UInt32 lhs, UInt32 rhs) -> std::optional<JoinKind>
 {
 if (std::popcount(lhs) == 1)
 {
 const auto & restriction = dpsub_data.restriction_by_rel[std::countr_zero(lhs)];
 if (restriction.present)
 {
 /// If there are any bits set in `restriction.required`
 /// that are not set in `rhs`, the bitwise AND (&) results in a non-zero value
 if (restriction.required & ~rhs)
 return {};
 return restriction.kind;
 }
 }
 return JoinKind::Inner;
 };

and then combines the two sides’ requirements, with a conflict rule at the end:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:310
 if (left_join_type == JoinKind::Inner)
 return right_join_type;
 if (right_join_type == JoinKind::Inner)
 return left_join_type;
 if (left_join_type == JoinKind::Full && right_join_type == JoinKind::Full)
 return JoinKind::Full;

 /// Conflicting outer-join constraints, the order is not possible
 return {};

Conflict detectors

The per-relation restriction above is sound but incomplete: it rejects some reorderings that are actually legal. The “conflict detector” machinery is the attempt to be complete. The setting chooses one:

 cpp
 
 
// src/Core/Settings.cpp:11272
 DECLARE(JoinOrderConflictDetector, query_plan_optimize_join_order_conflict_detector, JoinOrderConflictDetector::NONE, R"(
Only affects the `dpsub` join order algorithm. Selects the conflict detector that DPsub uses to
decide which join reorderings are valid. The following values are available:
 - `''` (default) - no conflict detector, DPsub uses the per-relation `ON` clause restriction
 - `'a'` - the CD-A conflict detector, which is correct but incomplete
 - `'c'` - the CD-C conflict detector, which is correct and complete
)", EXPERIMENTAL, \

The detector’s job is to decide, for a given split of the relation set, whether the outer-join operators that straddle it are still valid there. The check is a set-containment test per operator:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:361
 /// Required-set containment. `forward` keeps the operator's (left, right) inputs aligned
 /// with (left_mask, right_mask); `mirrored` swaps them -- a valid equivalence for any of our
 /// operators via `reverseJoinKind` (Left<->Right, Full/Inner unchanged; for semi/anti it
 /// flips the preserved side). The two required sides are disjoint and, for a non-degenerate
 /// predicate, both non-empty, so at most one orientation can hold.
 bool forward = subset_of(op.required_left, left_mask) && subset_of(op.required_right, right_mask);
 bool mirrored = subset_of(op.required_left, right_mask) && subset_of(op.required_right, left_mask);

and the “fail closed” rule is important — when the orientation is ambiguous, the split is rejected rather than guessed:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:392
 /// A non-inner operator whose orientation is still ambiguous (both sides admissible) would
 /// have its preserved side guessed; fail closed instead (see `reverseJoinKind`, which flips
 /// Left<->Right / the semi/anti preserved side while `buildPhysicalPlan` keeps the child order).
 if (forward && mirrored)
 return std::nullopt;

DPsub also refuses to run on a graph that only cross products hold together:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSub.cpp:608
 /// Turn down a graph that only cross products hold together, before enumerating anything: DPsub
 /// cannot stitch its components, so the next algorithm in the chain plans the query instead.
 if (dpsub_data.disconnected_graph)

The budget and the fallback chain

Both the DPsize and DPhyp searches are bounded by a deterministic budget — a count of enumerated partial plans, not a wall-clock timer:

 cpp
 
 
// src/Core/Settings.cpp:3121
DECLARE(UInt64, query_plan_optimize_join_order_max_searched_plans, 100000, R"(
Maximum number of partial plans the join order optimizer may enumerate before giving up and falling back to the next algorithm in `query_plan_optimize_join_order_algorithm`.
This bounds optimization time deterministically (independent of wall-clock) on dense join graphs such as cliques or stars, where the search space grows exponentially.
Set to 0 to disable the limit. Has no effect on the default `query_plan_optimize_join_order_limit`, where the search always stays well below this bound.
)", EXPERIMENTAL, \

The check is inside the enumeration loop:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:95
 ++searched_plans;
 if (max_searched_plans && searched_plans > max_searched_plans)
 {
 LOG_TRACE(log, "Exceeded the limit of {} searched plans, falling back", max_searched_plans);
 return nullptr;
 }

and the cancellation check is polled only every 4096 plans, because it can send progress over the network:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderDPSize.cpp:101
 /// `checkLimits` invokes the interactive cancel callback, which can send progress over
 /// the network. Poll it once every few thousand pairs instead of on every one.
 if ((searched_plans & 0xFFF) == 0)
 checkLimits();

When the budget is blown, the algorithm returns nullptr — and the chain moves on:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.cpp:371
 for (const auto & algorithm : enabled_algorithms)
 {
 LOG_TRACE(log, "Solving join order using {} algorithm", toString(algorithm));
 switch (algorithm)
 {
 case JoinOrderAlgorithm::DPSUB:
 best_plan = solveDPSubJoinOrder(query_graph);
 break;
 case JoinOrderAlgorithm::DPSIZE:
 best_plan = solveDPSizeJoinOrder(query_graph, max_searched_plans, query_status, interactive_cancel_callback);
 break;
 case JoinOrderAlgorithm::DPHYP:
 best_plan = solveDPHypJoinOrder(query_graph, max_searched_plans, query_status, interactive_cancel_callback);
 break;
 case JoinOrderAlgorithm::GREEDY:
 best_plan = solveGreedyJoinOrder(query_graph);
 if (!best_plan)
 throw Exception(ErrorCodes::LOGICAL_ERROR, "Failed to find a valid join order with greedy algorithm");
 break;
 }

 if (best_plan)
 break;
 }

The greedy algorithm is the last resort and the only one that cannot fail — it can always produce a valid order, because the original order is always valid. That is why it is the default and the fallback.

Each algorithm also clears the memo when it starts, so a failed attempt does not poison the next one:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:45
 /// Discard any partial state left by an earlier algorithm in the fallback chain
 /// (e.g. `dphyp,greedy`) so cost-model lookups via `getColumnStats` only see
 /// entries built by this run. `expression_selectivity` is cleared along with
 /// `dp_table` because multi-relation predicates resolve NDV through it.
 dp_table.clear();
 expression_selectivity.clear();

Choosing an algorithm

 sql
 
 
-- Inner joins only, small graph, want the best plan:
SETTINGS query_plan_optimize_join_order_algorithm = 'dpsize';

-- Inner joins, sparse graph, want it fast:
SETTINGS query_plan_optimize_join_order_algorithm = 'dphyp';

-- Outer joins, want completeness:
SETTINGS query_plan_optimize_join_order_algorithm = 'dpsub';

-- Best of both: try the DP, fall back to greedy if it declines.
SETTINGS query_plan_optimize_join_order_algorithm = 'dphyp,greedy';

Trade-offs

The memo is the whole trick. Everything else in these files exists to make the memo’s key small and its value cheap. The key is a bitmask; the value is four numbers and two pointers.

The DP algorithms are not free, and the budget is what makes them safe. The 100 000-plan budget is a deterministic bound — two runs of the same query enumerate the same number of plans, so the optimizer’s runtime is predictable. A wall-clock timeout would have been simpler and worse: it would make the chosen plan depend on machine load, which is a nightmare to debug.

Outer joins are where completeness gets expensive. The per-relation restriction is cheap and rejects legal reorderings; the conflict detectors are complete but cost more per candidate, and they only apply to DPsub. This is why the setting’s scope is narrow: “Only affects the dpsub join order algorithm”.

The algorithms decline rather than guess. Every one of them has an explicit “give up” path — DPhyp on disconnected graphs, DPsub on graphs it cannot stitch, both on budget exhaustion — and every give-up hands the query to the next algorithm in the chain. A join-order optimizer that always returns a plan is safe; one that returns a wrong plan is not.

What the DP buys you in practice. For the star query, the greedy algorithm usually gets it right, because the cost model naturally prefers joining the small dimension tables first. The DP algorithms matter when the graph is a chain, or when a medium table must be joined to a large one before a cross-product-forming pair, and the greedy choice has to be revised two steps later. On those shapes, the DP plan can be an order of magnitude better — and on the shapes where they are not, the budget means you do not pay much.

ClickHouse Reorders Joins by Turning the Join Tree into a Graph

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: The join tree you typed is flattened into a QueryGraph of relations and edges; a search algorithm (greedy by default, DP variants optionally) picks a cheaper binary tree over that graph; the plan is then rebuilt from scratch in the winning order, with a fresh JoinStepLogical per step.

A join order is the classic example of a decision that is trivial to state and catastrophic to get wrong.

 sql
 
SELECT * FROM a JOIN b ON a.id = b.id JOIN c ON b.id = c.id;

Written left-to-right, this is (a ⋈ b) ⋈ c. Written the other way it is a ⋈ (b ⋈ c). Both are legal SQL, they return the same rows, and one of them can be a hundred times faster than the other — because the intermediate result of the inner join is either 10 rows or 10 billion rows, and everything downstream pays for that.

The number of legal binary trees over N relations is the Catalan number C(N): 2 for N=2, 5 for N=3, 14 for N=4, 42 for N=5, 132 for N=6, 429 for N=7. For N=10 it is 16 796. A cost-based optimizer wants to look at all of them; a real query planner cannot afford to.

ClickHouse’s answer is a three-stage pipeline:

 text
 
 
 SQL join tree QueryGraph DPJoinEntry tree
 (JoinStepLogical) ┌──────────────────────┐ ┌────────────────────┐
 a ⋈ (b ⋈ c) ──────►│ relations[] edges[] │ ────► │ Join(Join(Leaf)) │
 │ join_kinds[] │ │ cost, cardinality, │
 │ column_equivalences │ │ join_operator │
 └──────────────────────┘ └────────────────────┘
 │ │
 greedy / dpsize / rebuild:
 dphyp / dpsub new JoinStepLogical
 per step

This article walks the whole path: how the tree becomes a graph, how the graph becomes a search problem, and how the winning tree becomes a new plan.

The switch

Two settings control the whole thing. The first says how much to optimize:

 cpp
 
 
// src/Core/Settings.cpp:3115
DECLARE(UInt64, query_plan_optimize_join_order_limit, 10, R"(
Optimize the order of joins within the same subquery. Currently only supported for very limited cases.
Value is the maximum number of tables to optimize.
)", 0, \
 {"25.12", 1, 10, "Allow JOIN reordering with more tables by default"}, \
 {"25.9", 1, 1, "New setting"}) \

Ten relations is the default cap on how many relations the flattened graph may contain before the optimizer refuses to flatten further. The second says which algorithm to use:

 cpp
 
 
// src/Core/Settings.cpp:11263
DECLARE(JoinOrderAlgorithm, query_plan_optimize_join_order_algorithm, "greedy", R"(
Specifies which JOIN order algorithms to attempt during query plan optimization. The following algorithms are available:
 - 'greedy' - basic greedy algorithm - works fast but might not produce the best join order
 - 'dpsize' - implements DPsize algorithm currently only for Inner joins - considers all possible join orders and finds the most optimal one but might be slow for queries with many tables and join predicates.
 - 'dpsub' - implements DPsub algorithm which supports both inner and non-inner joins - considers all possible join orders and finds the most optimal one but might be slow for queries with many tables and join predicates.
 - 'dphyp' - implements DPhyp (Dynamic Programming via Hypergraph Partitioning) algorithm currently only for inner joins - explores the same search space as `dpsize` but enumerates only connected subgraph pairs, which generates fewer intermediate joins on sparse join graphs, at the cost of not considering cross products
Multiple algorithms can be specified as a comma-separated list, e.g. `dphyp,greedy`. They are tried in order; if an algorithm cannot handle the query (e.g. due to outer joins or disconnected components), the next one is used as a fallback.
)", EXPERIMENTAL, \
 {"25.12", "greedy", "greedy", "New experimental setting."}) \

Note the fallback semantics: the setting is a list, and each algorithm may decline the query, handing over to the next.

Before any of that, the optimizer checks whether the query is even eligible:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1492
 const auto & join_operator = join_step->getJoinOperator();
 auto strictness = join_operator.strictness;
 auto kind = join_operator.kind;
 auto locality = join_operator.locality;
 if (!optimization_settings.query_plan_optimize_join_order_limit
 || (strictness != JoinStrictness::All && !isSwapOnlyJoinStrictness(strictness))
 || locality != JoinLocality::Unspecified
 || kind == JoinKind::Paste
 || !join_operator.residual_filter.empty()
 )
 {
 join_step->setOptimized();
 return;
 }

JoinStrictness::All is the plain INNER JOIN case. ANY/SEMI/ANTI joins are swap-only — they may exchange their two inputs but not be reordered around each other — and FULL JOIN is swap-only too:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1513
 int query_graph_size_limit = safe_cast<int>(optimization_settings.query_plan_optimize_join_order_limit);
 if ((isSwapOnlyJoinStrictness(strictness) || isSwapOnlyJoinKind(kind)) && query_graph_size_limit > 2 && !cda_reorder_semi_anti)
 /// Do not reorder joins, only allow swap
 query_graph_size_limit = 2;

Building the graph

The graph builder walks the QueryPlan tree top-down. At each JoinStepLogical it asks two questions: can the left subtree be flattened into the same graph (the join becomes an edge rather than a subtree), and can the right subtree?

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:691
 auto type_changing_sides = join_step->typeChangingSides();
 bool allow_left_subgraph = !type_changing_sides.contains(JoinTableSide::Left) && (isInnerOrCross(join_kind) || isLeft(join_kind));
 bool allow_right_subgraph = !type_changing_sides.contains(JoinTableSide::Right) && (isInnerOrCross(join_kind) || isRight(join_kind));

Three gates, each of which exists because of a real bug class:

Type-changing sides. A LEFT JOIN with join_use_nulls = 1 makes the right side’s columns Nullable. If the optimizer is allowed to move that relation elsewhere in the tree, the type change would be applied at the wrong step. The comment says it outright:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:504
 /// Do not flatten joins that have type-changing sides (e.g., LEFT JOIN
 /// with `join_use_nulls` making right-side columns Nullable). Flattening
 /// such joins allows the optimizer to reorder them, which can separate
 /// a relation from the join that causes its type change, leading to
 /// type changes being applied at the wrong step and the exception
 /// "Cannot fold actions for projection".

Join kind. The left subtree of a RIGHT JOIN may not be flattened (allow_left_subgraph requires isInnerOrCross(join_kind) || isLeft(join_kind)), because a RIGHT JOIN is not commutative with respect to null-extension.

Column-name clashes. Two relations that expose the same column name cannot be merged into one flat namespace:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:729
 if (std::ranges::any_of(lhs_cols, [&](const auto & name) { return rhs_cols.contains(name); }))
 {
 LOG_DEBUG(getLogger("optimizeJoin"), "Column name clash detected between join sides, disabling subgraph flattening");
 allow_left_subgraph = false;
 allow_right_subgraph = false;
 }

When a subtree is flattened, its relations become sibling leaves of the graph and the join between them becomes an edge. The builder merges the two child graphs, shifting the child’s relation ids so that the restrictions recorded for the outer joins keep pointing at the right relations:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:368
 for (auto & [id, restriction] : rhs.join_kinds)
 {
 restriction.first.shift(shift);
 lhs.join_kinds[id + shift] = std::move(restriction);
 }

The shape of a graph

The result is a small, explicit structure:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.h:89
struct QueryGraph
{
 std::vector<RelationStats> relation_stats;

 std::vector<JoinActionRef> edges;

 /// Operators of the original join tree, in tree (not enumeration) order. Populated during
 /// `buildQueryGraph` and consumed by the conflict detector (CD-A/CD-C) when it is enabled; empty
 /// otherwise. See `ConflictJoinOp`.
 std::vector<ConflictJoinOp> conflict_ops;

with a BitSet per relation set. The BitSet is a thin wrapper over boost::dynamic_bitset that tolerates operands of different widths:

 cpp
 
 
// src/Interpreters/JoinExpressionActions.h:34
class BitSet
{
private:
 using Base = boost::dynamic_bitset<>;

A relation set of {0, 3, 7} is one bitwise-OR away from another, which is exactly the operation the DP memo needs.

Outer joins: the restriction that makes reordering legal

Reordering an inner join is free. Reordering an outer join is not: a LEFT JOIN b must be evaluated before b is joined to c, or the null-extension happens at the wrong moment. The graph records this as a restriction on the null-supplying relation:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.h:105
 /// Restriction for a null-supplying relation of an outer join.
 /// Maps (relation id) -> (set of relations referenced by the outer join's ON clause, join kind).
 /// The relation may be joined (as a singleton side) only against a set that contains all
 /// relations its ON clause depends on; the remaining relations may be joined outside.
 std::unordered_map<size_t, std::pair<BitSet, JoinKind>> join_kinds;

and the builder fills it in when it sees a LEFT/RIGHT/FULL join:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:849
 if (isRightOrFull(join_kind))
 {
 if (lhs_count != 1)
 throw Exception(ErrorCodes::LOGICAL_ERROR, "JoinStepLogical with RIGHT or FULL join must have exactly one left input, but has {}", lhs_count);
 join_expression_sources.set(0, false);
 query_graph.join_kinds[0] = std::make_pair(join_expression_sources, join_kind);
 }
 if (isLeftOrFull(join_kind))
 {
 if (rhs_count != 1)
 throw Exception(ErrorCodes::LOGICAL_ERROR, "JoinStepLogical with LEFT or FULL join must have exactly one right input, but has {}", rhs_count);
 join_expression_sources.set(total_inputs - 1, false);
 query_graph.join_kinds[total_inputs - 1] = std::make_pair(join_expression_sources, join_kind);
 }

The ON-clause predicates of an outer join are pinned to the step that joins the null-supplying relation, because there they mean “matching” and not “filtering”:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.h:111
 /// Predicates from the ON clause of an outer join, mapped to the id of the null-supplying
 /// relation. Such a predicate must be applied in the ON clause of the join step that joins
 /// this relation: it affects matching, not filtering (rows of the preserved side are kept
 /// even when the predicate doesn't hold).
 /// All other predicates are filters: they may be applied at any step where all their source
 /// relations are available, but they must not be merged into an outer join's ON clause -
 /// they go to the post-join `residual_filter` instead.
 std::unordered_map<JoinActionRef, size_t> outer_join_conditions;

Every candidate join order is then checked against these restrictions by isValidJoinOrder, which is a small, sharp function:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderBitSet.cpp:14
 auto check = [&](const auto & lhs, const auto & rhs) -> std::optional<JoinKind>
 {
 auto rel_id = lhs.getSingleBit();
 if (rel_id.has_value())
 {
 auto it = query_graph.join_kinds.find(rel_id.value());
 if (it != query_graph.join_kinds.end())
 {
 if (isSubsetOf(it->second.first, rhs))
 return it->second.second;
 return {};
 }
 }
 return JoinKind::Inner;
 };

If the restricted relation’s dependency set is not a subset of the other side, the pair is simply not joinable — the function returns an empty optional and the candidate is discarded. The comment at the bottom of the function explains the classic case:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderBitSet.cpp:55
 /// Conflict, join is not possible:
 /// FROM t1 LEFT JOIN t2 LEFT JOIN t3
 /// t1 -> Inner, t2 -> Left, t3 -> Left
 /// Cannot do (t2 x t3)
 return {};

Transitive predicates

A.x = B.x AND B.x = C.x implies A.x = C.x, and an optimizer that can see that can consider joining A to C directly. ClickHouse builds equivalence classes over the join keys:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.h:120
 /// Column equivalence classes derived from equi-join edges (e.g., A.x = B.x AND B.x = C.x
 /// implies A.x, B.x, C.x are all equivalent). Used by the join order optimizer to detect
 /// transitive connectivity between relations without synthesizing extra edges.
 /// Stored as alias-resolved JoinActionRef-s pointing to INPUT nodes.
 EquivalenceClasses<JoinActionRef> column_equivalences;

and it refuses to build a class across an outer join, because an outer join’s equality does not hold for the null-padded rows:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.cpp:140
 /// Skip predicates involving outer-joined relations: when a LEFT/RIGHT/FULL JOIN
 /// doesn't match, the outer side produces NULLs, so the equality doesn't hold
 /// for all rows and the transitive equivalence would be invalid.

The synthesis happens after the search, as a post-pass over the winning tree, so that the search itself can use the connectivity without materialising redundant predicates:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.cpp:262
 /// Phase 2: Synthesize predicates for equivalence classes spanning both subtrees.

and the synthesized predicate is a real one, added to the join operator:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.cpp:311
 expressions.push_back(JoinActionRef::transform(
 {member, other},
 JoinActionRef::AddFunction(JoinConditionOperator::Equals)));

The greedy search

The default algorithm is the simplest possible one: repeatedly pick the pair of components whose join is cheapest, merge them, repeat.

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:52
 std::deque<std::shared_ptr<DPJoinEntry>> components;
 for (size_t i = 0; i < query_graph.relation_stats.size(); ++i)
 {
 const auto & rel = query_graph.relation_stats[i];
 components.push_back(std::make_shared<DPJoinEntry>(i, rel.estimated_rows, rel.column_stats));
 }

Every iteration scans all pairs:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:69
 for (size_t i = 0; i < components.size(); i++)
 {
 for (size_t j = i + 1; j < components.size(); j++)
 {
 auto left = components[i];
 auto right = components[j];

 auto join_kind = isValidJoinOrder(query_graph, left->relations, right->relations);
 if (!join_kind)
 continue;

The cost of a candidate is the cost of the two inputs plus the estimated number of matched pairs the join produces:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:223
inline double computeJoinCost(const DPJoinEntryPtr & left, const DPJoinEntryPtr & right, const SelectivityEstimate & selectivity)
{
 return left->cost + right->cost + estimateJoinedRows(selectivity, left->estimated_rows, right->estimated_rows);
}

The subtlety is the tie-break. A pair with no equality predicate is a cross product, and a cross product’s cost estimate is rows_left * rows_right — which is enormous — unless one side has no row estimate at all, in which case the missing side is charged as a single row and the cross product looks free. The greedy algorithm guards against that by preferring any equi-connected pair over any non-equi pair regardless of cost:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:90
 /// An equi-connected pair always supersedes one without an equi key, regardless of
 /// cost: without an equi predicate the cost estimate is essentially a cross product
 /// (a relation without a row estimate makes it look arbitrarily small), so such a
 /// pair that happened to be evaluated first must not shadow valid equi-joined plans.
 if (!best_plan || (equi_connected && !best_plan_equi_connected)
 || (equi_connected == best_plan_equi_connected && current_cost < best_plan->cost))

There is a second subtlety: a filter predicate that mentions one relation only must not be smuggled into an outer join’s ON clause, where it would change matching semantics:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:102
 for (const auto * e : edges)
 {
 /// A filter predicate applied at an outer join step must not go to the
 /// ON clause, where it would affect matching instead of filtering and
 /// let non-matching rows of the preserved side survive NULL-extended.
 /// Apply it after the join instead.
 if (is_inner_step || query_graph.outer_join_conditions.contains(*e))
 join_operator.expression.push_back(*e);
 else
 join_operator.residual_filter.push_back(*e);
 }

The merge itself is a two-line splice, and the search ends with exactly one component:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderGreedy.cpp:140
 components.erase(components.begin() + std::max(best_i, best_j));
 components.erase(components.begin() + std::min(best_i, best_j));
 components.push_front(best_plan);
 dp_table[best_plan->relations] = best_plan;

Rebuilding the plan

The search produces a DPJoinEntry tree. Turning it back into a QueryPlan is the second half of the work, and it is a rebuild, not an edit: the original JoinStepLogical nodes are discarded and new ones are constructed.

The tree is flattened into a post-order sequence, so that each step’s children are already built when the step itself is built:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:868
static std::vector<DPJoinEntry *> getJoinTreePostOrderSequence(DPJoinEntryPtr root)
{
 std::vector<DPJoinEntry *> result;
 result.reserve(root->relations.count() * 2);

Then a stack machine walks it. Leaves push the original read node; join nodes pop two children and push the new join step:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1081
 for (size_t entry_idx = 0; entry_idx < sequence.size(); ++entry_idx)
 {
 auto * entry = sequence[entry_idx];
 if (entry->isLeaf())
 {
 /// Base relation, use this step as input node
 size_t relation_id = safe_cast<size_t>(entry->relation_id);
 if (relation_id >= input_nodes.size())
 throw Exception(ErrorCodes::LOGICAL_ERROR, "Invalid relation id: {}, input nodes size: {}", relation_id, input_nodes.size());
 node_stack.push(input_nodes[relation_id]);
 }
 else
 {
 /// Combine two nodes from the stack into a single join operation
 auto * left_child_node = node_stack.top();
 node_stack.pop();
 auto * right_child_node = node_stack.top();
 node_stack.pop();

At this point one more decision is made: which side builds the hash table. The estimator knows the row count of each side, and for a hash join you want the smaller side in the hash table:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1119
 auto lhs_estimation = entry->left->estimated_rows;
 auto rhs_estimation = entry->right->estimated_rows;

 bool swap_on_sizes = optimization_settings.join_swap_table.has_value()
 ? optimization_settings.join_swap_table.value()
 : entry->join_method == JoinMethod::Hash && lhs_estimation && rhs_estimation
 && lhs_estimation.value() < rhs_estimation.value();

 bool flip_join = has_prepared_storage_at_left || (!has_prepared_storage_at_right && swap_on_sizes);

and the flip reverses the join kind, because a LEFT join flipped becomes a RIGHT join:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1146
 if (flip_join)
 {
 /// For hash joins, we want to keep the smaller side on the right
 std::swap(left_rels, right_rels);
 std::swap(left_child_node, right_child_node);
 join_operator.kind = reverseJoinKind(join_operator.kind);
 }

Finally the new step is created and the estimates are attached to it, so that EXPLAIN can show them:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1299
 auto join_step = std::make_unique<JoinStepLogical>(
 left_header_ptr,
 right_header_ptr,
 std::move(join_operator),
 std::move(current_expression_actions),
 actions_after_join,
 join_settings,
 sorting_settings);

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:1323
 join_step->setOptimized(entry->estimated_rows, entry->column_stats, imprecise_estimate, entry->cost, entry->selectivity, cluster_id);

The imprecise_estimate flag is the honest part: it is true if any leaf of the subtree had an imprecise estimate, and it makes EXPLAIN render the row count with a ~~ prefix:

 cpp
 
 
// src/Processors/QueryPlan/JoinStepLogical.cpp:335
 if (imprecise_estimate)
 description.emplace_back("ResultRows", result_rows_estimation ? fmt::format("~~{}", result_rows_estimation.value()) : "unknown");
 else
 description.emplace_back("ResultRows", result_rows_estimation ? toString(result_rows_estimation.value()) : "unknown");

What it buys you, and what it costs

The win. For a star query — one big fact table, several small dimension tables — the difference between joining the dimensions first and joining them last is the difference between a 10-row intermediate and a 10-billion-row one. The greedy algorithm gets this right for the common shapes, and the DP algorithms get it right more often.

The cost. The optimizer has to be right, and “right” here means “produces the same rows”. The restrictions above are all consequences of cases where a reordering changed the result. The join_kinds restriction, the outer_join_conditions pinning, the type-change gate, the column-name-clash check, the join_use_nulls gate on null-rejection reasoning — each one exists because a simpler rule produced a wrong answer.

The cost of being wrong. A join-order optimizer that picks a bad order does not produce wrong rows, it produces slow queries. That is why the default algorithm is the cheap one and the expensive ones are opt-in and experimental.

The escape hatch.

 sql
 
 
SELECT * FROM a JOIN b ON a.id = b.id JOIN c ON b.id = c.id
SETTINGS query_plan_optimize_join_order_algorithm = 'greedy';

and, to see what the optimizer thinks:

 sql
 
 
EXPLAIN actions = 1, compact = 1, pretty = 1
SELECT * FROM t1 INNER JOIN t2 ON t1.id = t2.id;

 text
 
 
Join (JOIN FillRightFirst)
│ t1[100] ⋈ t2[100]
│ Type: inner | Strictness: all | Algorithm: SpillingHashJoin(HashJoin)
│ Cost: estimated 100.00
│ Selectivity: estimated (NDV) 0.01
│ Output rows: estimated 100.00
│ Left: rows estimated 100.00
│ Right: rows estimated 100.00
│ Join conditions: id = id

The number in brackets is the estimated row count of the relation, and the Cost line is the number the optimizer minimised. The next article in this series digs into where those numbers come from.

ClickHouse Estimates Join Cardinality from Distinct-Value Counts

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: Column statistics (NDV from a uniq sketch, min/max, null counts) become per-relation row estimates; an equality between two join keys gets selectivity 1 / max(NDV_left, NDV_right); the join’s output cardinality is that selectivity times the product of the two sides, floored by the preserved side for outer joins. The whole model lives in joinOrderCommon.h.

A join-order optimizer is a search algorithm wearing a costume. The search itself is generic — enumerate candidate trees, score them, pick the best — and all of the intelligence lives in the scoring function. Get the score wrong and the search is a very expensive way to pick a bad plan.

ClickHouse’s scoring function is remarkably small, and it is worth understanding in full, because the number it produces shows up in EXPLAIN output and people try to read it as a promise.

It is not a promise. It is a guess with a documented error bar, and the whole pipeline that produces it is:

 text
 
 
 per-part column statistics per-relation estimate
 ┌───────────────────────────┐ ┌────────────────────────┐
 │ uniq sketch -> NDV │ │ estimated_rows │
 │ minmax -> [min,max] │ ────► │ column_stats[col].ndv │
 │ basic -> nulls │ │ (per column) │
 └───────────────────────────┘ └────────────────────────┘
 │ │
 │ selectivity of a predicate │ 1 / max(NDV)
 ▼ ▼
 ┌──────────────────────────────────────────────────┐
 │ SelectivityEstimate { value, reported_value } │
 └──────────────────────────────────────────────────┘
 │
 ▼
 ┌──────────────────────────────────────────────────┐
 │ estimateJoinCardinality() -> rows of the join │
 │ computeJoinCost() -> cost of the join │
 └──────────────────────────────────────────────────┘

Where the numbers come from

ClickHouse stores per-column statistics inside each MergeTree part. Three kinds matter here:

uniq / uniqCombined64 — distinct-value sketches. The plain uniq statistics object is literally the uniq aggregate function’s state; the V2 variant is uniqCombined64 with K = 12, which is exact for a handful of values, a hash set up to 256 of them, and a HyperLogLog above that.
minmax / basic — the minimum and maximum value, and (for basic) the null count and the default count.
tdigest, countmin — distribution sketches, used for < and = selectivity.

The per-part objects are merged into a per-column object. The NDV question has a fallback that is important to know about:

 cpp
 
 
// src/Storages/Statistics/Statistics.cpp:446
UInt64 ColumnStatistics::estimateCardinality() const
{
 if (const IStatistics * uniq_stats = findUniqStats(stats))
 {
 return uniq_stats->estimateCardinality();
 }
 /// if we don't have uniq statistics, we use a mock one, assuming there are 90% different unique values.
 return UInt64(static_cast<Float64>(rows) * ConditionSelectivityEstimator::default_cardinality_ratio);
}

With no uniq sketch, the column is assumed to have 10 % distinct values (default_cardinality_ratio = 0.1). That is a guess, and the guess propagates: the last fallback of estimateEqual divides the non-NULL row count by the distinct-value count to answer “how many rows have this value?”:

 cpp
 
 
// src/Storages/Statistics/Statistics.cpp:404
 if (uniq_stats != nullptr)
 {
 UInt64 cardinality = uniq_stats->estimateCardinality();
 if (cardinality == 0 || rows == 0)
 return 0;
 /// Uniq ignores NULLs, so divide non-NULL row count by distinct values.
 /// `getNonNullRowCount` returns `rows` when null-count tracking is absent.
 return static_cast<Float64>(getNonNullRowCount()) / static_cast<Float64>(cardinality);
 }

 return std::nullopt;

Before reaching that fallback, estimateEqual tries the distribution sketches, in descending order of accuracy — basic first, then a t-digest, then a count-min sketch:

 cpp
 
 
// src/Storages/Statistics/Statistics.cpp:389
 const IStatistics * uniq_stats = findUniqStats(stats);
 if (stats_desc.data_type->isValueRepresentedByNumber() && uniq_stats != nullptr && stats.contains(StatisticsType::TDigest))
 {
 /// 2048 is the default number of buckets in TDigest. In this case, TDigest stores exactly one value (with many rows) for every bucket.
 if (uniq_stats->estimateCardinality() < 2048)
 {
 return stats.at(StatisticsType::TDigest)->estimateEqual(val);
 }
 }

That “2048” is a nice piece of engineering folklore: a t-digest with more buckets than there are distinct values has one value per bucket, so it can answer an equality exactly.

From statistics to a relation estimate

The unit the join optimizer consumes is a RelationStats:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatistics.h:16
struct RelationStats
{
 std::optional<UInt64> estimated_rows = {};
 std::optional<Float64> avg_row_bytes = {};
 std::unordered_map<String, ColumnStats> column_stats = {};

 String table_name;
 bool imprecise_estimate = false;

 /// Diagnostic annotation of where `estimated_rows` came from; see `RowEstimateSource`.
 /// `NoSource` means the producer of the estimate did not track it; set it wherever it is known.
 RowEstimateSource source = RowEstimateSource::NoSource;
};

and the per-column part of it is just an NDV plus some optional extras:

 cpp
 
 
// src/Storages/Statistics/ConditionSelectivityEstimator.h:14
struct ColumnStats
{
 UInt64 num_distinct_values = 0;
 /// Average uncompressed size of one value; 0 means unknown.
 Float64 avg_bytes = 0;
 /// Value range from `basic`/`minmax` statistics; unset when unknown.
 std::optional<Field> min_value = {};
 std::optional<Field> max_value = {};
 /// Fraction of NULL values; unset when unknown.
 std::optional<Float64> null_fraction = {};
};

estimateReadRowsCount is the function that produces a RelationStats for any plan node. For a MergeTree read it does three things: analyse the ranges, ask the statistics estimator for a selectivity-adjusted row count, and fall back to the primary index’s row count if there is no statistics.

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatisticsEstimator.cpp:238
 const bool use_statistics = reading->getContext()->getSettingsRef()[Setting::use_statistics];
 if (use_statistics)
 {
 if (auto estimator = reading->getConditionSelectivityEstimator(reading->getAllColumnNames(), analyzed_result))
 {
 auto relation_profile = estimator->estimateRelationProfile(reading->getStorageMetadata(), filter, prewhere_node);
 RelationStats stats{
 .estimated_rows = relation_profile.rows,
 .column_stats = relation_profile.column_stats,
 .table_name = table_display_name,
 .source = RowEstimateSource::Statistics};
 LOG_TRACE(getLogger("optimizeJoin"), "estimate statistics {}", dumpStatsForLogs(stats));
 return stats;
 }
 }

If the filter is not usable by the primary index, the estimate is withheld rather than faked:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatisticsEstimator.cpp:263
 /// If any conditions are pushed down to storage but not used in the index,
 /// we cannot precisely estimate the row count
 if (has_filter && !is_filtered_by_index)
 return RelationStats{
 .estimated_rows = {},
 .table_name = table_display_name,
 .imprecise_estimate = true,
 .source = RowEstimateSource::NoStatistics};

An unknown row count is not the same as a row count of zero, and the difference matters: the cost model treats an unknown side as one row so that a cross product with an unknown side does not look free, but it must not be treated as empty.

Aggregation subqueries

A subquery that aggregates is a relation too, and its row count is the number of groups:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatisticsEstimator.cpp:78
 UInt64 key_number_of_distinct_values = key_stats->second.num_distinct_values;

 if (input_stats.estimated_rows)
 key_number_of_distinct_values = std::min(key_number_of_distinct_values, *input_stats.estimated_rows);

 aggregation_stats.column_stats[key].num_distinct_values = key_number_of_distinct_values;

 /// For now assume that aggregation columns are independent, so multiply their NDVs
 if (total_number_of_distinct_values)
 *total_number_of_distinct_values *= static_cast<Float64>(key_number_of_distinct_values);

The independence assumption is worth flagging: GROUP BY a, b is estimated as NDV(a) * NDV(b), which is wrong whenever a and b are correlated, and it is clamped to the input row count so it cannot exceed reality by more than the correlations allow.

Selectivity

Now the interesting part: what does a.x = b.y keep?

The answer is 1 / max(NDV(a.x), NDV(b.y)), and the implementation says so explicitly:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:68
/// Accounts for an equality between key columns with the largest NDV `max_ndv` (0 if unknown)
/// and the largest NDV upper bound `max_ndv_upper_bound` (0 if unknown), see `ColumnDistinctValues`.
inline void applyEquiKeyDistinctValues(SelectivityEstimate & estimate, UInt64 max_ndv, UInt64 max_ndv_upper_bound)
{
 estimate.has_equi = true;
 if (max_ndv > 0)
 {
 estimate.value = std::min(estimate.value, 1.0 / static_cast<double>(max_ndv));
 estimate.reliable = true;
 }
 if (max_ndv_upper_bound > 0)
 estimate.reported_value = std::min(estimate.reported_value, 1.0 / static_cast<double>(max_ndv_upper_bound));
}

The intuition is the standard one: if the key has D distinct values spread uniformly over N rows, each value appears N/D times, so a lookup of one value keeps a fraction 1/D of the other side.

Note there are two numbers, not one, and the distinction is subtle but important:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:18
struct SelectivityEstimate
{
 double value = 1.0;
 /// Like `value`, but a key column without NDV statistics uses the row count of its relation
 /// (an upper bound of its NDV) instead. Reported by `EXPLAIN` as `estimated (NDV)` and used for the
 /// match fraction of semi/anti joins; the inner join cost model does not use it, because it says
 /// nothing about which side is the key.
 double reported_value = 1.0;
 bool reliable = false;
 bool has_equi = false;
};

value is the measured selectivity: 1/NDV when the NDV is known.
reported_value is the upper bound version: 1/row_count when the NDV is not known, since a column cannot have more distinct values than the relation has rows.

reliable says which one applies, and the difference changes the cardinality formula, because reliability is also the signal for “which side is the key”.

The cardinality formula

Here is the entire model:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:135
inline double estimateJoinedRows(
 const SelectivityEstimate & selectivity, std::optional<UInt64> lhs_rows, std::optional<UInt64> rhs_rows)
{
 double lhs = static_cast<double>(lhs_rows.value_or(1));
 double rhs = static_cast<double>(rhs_rows.value_or(1));
 if (!lhs_rows || !rhs_rows)
 return selectivity.reported_value * lhs * rhs;
 if (selectivity.reliable)
 return selectivity.value * lhs * rhs;
 if (selectivity.has_equi)
 return std::max(lhs, rhs);
 return lhs * rhs;
}

Read it as four cases:

One side unknown → the result is unknown too, and the formula falls back to the upper-bound selectivity.
Reliable NDV on both sides → selectivity * lhs * rhs. The textbook answer.
Equi-join, but NDV unknown → max(lhs, rhs). This is the foreign-key/primary-key heuristic: if b.y is a unique key, then joining a to b produces at most a’s row count, and the model assumes the larger side is preserved.
No equi condition at all → the full cross product lhs * rhs.

Case 3 is the “we don’t know which side is the key, so assume the bigger side survives” fallback, and the comment above the function explains why it is shaped that way:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:125
/// Expected number of rows an inner join of `lhs_rows` x `rhs_rows` keeps under `selectivity`.
/// When a side has no row estimate we cannot tell which side is the key, so the join is costed as
/// before the FK->PK heuristic: the missing row estimate counts as 1 row and the selectivity is the
/// NDV upper bound (`reported_value`), whatever `reliable` says. A join with an unknown relation must
/// not look more expensive than that, otherwise the only relations with known sizes (for example,
/// those with hash-table statistics hints) are pushed to the end of the join order, and a key whose
/// relation has a known size must keep making the join with it cheap even when the other side is a
/// sub-join of unknown size. With both sizes known, an equi join without reliable NDV is assumed to
/// be FK->PK (the smaller side is a unique key), so it keeps the larger side. Without any equi
/// condition (cross or range-only join) the result is the full product.

That is a long comment, and it is worth reading twice, because it encodes a failure mode that cost real debugging time: if a join with an unknown side looks more expensive than a join with two known sides, the optimizer will shove the known-size relations to the end of the order — which is exactly the wrong answer for a star query.

Outer joins

The outer-join rules are a floor, applied on top of the inner formula:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:195
 double joined_rows = std::max(estimateJoinedRows(selectivity, left_rows, right_rows), 1.0);

 if (join_kind == JoinKind::Left)
 joined_rows = std::max(joined_rows, lhs);
 if (join_kind == JoinKind::Right)
 joined_rows = std::max(joined_rows, rhs);
 if (join_kind == JoinKind::Full)
 joined_rows = std::max(joined_rows, lhs + rhs);

LEFT keeps at least every left row (null-padded when unmatched), RIGHT at least every right row, FULL at least the sum.

Semi and anti joins

Semi and anti joins are filters, not expansions, and treating them like outer joins is a classic optimizer bug — it makes a selective semi join look like a row multiplier, so the optimizer refuses to push it down. ClickHouse models them explicitly:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrderCommon.h:173
 if (strictness == JoinStrictness::Semi || strictness == JoinStrictness::Anti)
 {
 /// Preserved side is the left input for LEFT (and Inner/Cross, defensively), the right
 /// input for RIGHT; the other side is only probed for existence.
 const bool preserve_left = !isRight(join_kind);
 const double preserved = preserve_left ? lhs : rhs;
 const double other = preserve_left ? rhs : lhs;
 /// Expected fraction of preserved rows with at least one match. The selectivity is ~1/ndv,
 /// so `ndv_selectivity * other` approximates matches per preserved row; cap at 1. Without
 /// reliable statistics use the row-count upper bound of NDV (`reported_value`), which treats
 /// the join as FK->PK: e.g. a semi join of 1000 rows against 10 keys keeps ~10 rows.
 const double ndv_selectivity = selectivity.reliable ? selectivity.value : selectivity.reported_value;
 const double match_fraction = std::min(1.0, ndv_selectivity * other);
 const double kept = (strictness == JoinStrictness::Semi)
 ? preserved * match_fraction
 : preserved * (1.0 - match_fraction);

A semi join of 1000 rows against a 10-key side keeps about 1000 * min(1, 0.1 * 10) = 1000 rows, i.e. everything, because the 10 keys cover all 1000 rows. An anti join of the same shape keeps 0.

NDV propagation through the join tree

A cardinality estimate is only as good as the NDVs feeding it, and NDVs change as you join. Two mechanisms keep them honest.

Merging. When a join is built, the two children’s column statistics are merged, and the NDVs of the equi-join key columns are tightened to the minimum of the two sides:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatistics.cpp:35
 const UInt64 minimum = std::min(left_stats.num_distinct_values, right_stats.num_distinct_values);
 if (update_left)
 left_stats.num_distinct_values = minimum;
 if (update_right)
 right_stats.num_distinct_values = minimum;

Which side gets tightened depends on the join kind, because an outer join preserves one side’s keys untouched:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/RelationStatistics.cpp:26
 else if (strictness != JoinStrictness::Anti)
 {
 /// An outer join preserves the named side, so only the non-preserved side can lose key values.
 update_left = kind == JoinKind::Inner || kind == JoinKind::Right
 || kind == JoinKind::Cross || kind == JoinKind::Comma;
 update_right = kind == JoinKind::Inner || kind == JoinKind::Left
 || kind == JoinKind::Cross || kind == JoinKind::Comma;
 }

Capping. A join cannot produce more distinct values in a column than it produces rows, and the constructor enforces it:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/joinOrder.cpp:99
 /// Cap all NDVs at the estimated output rows.
 if (cardinality_)
 {
 for (auto & [_, stats] : column_stats)
 stats.num_distinct_values = std::min(stats.num_distinct_values, *cardinality_);
 }

This is the mechanism that stops a chain of joins from inflating the NDV without bound: after a ⋈ b produces 100 rows, every column of the result has an NDV of at most 100, and the next join’s selectivity is computed from that.

Reading the numbers in EXPLAIN

The estimates are surfaced, with a documented meaning:

 cpp
 
 
// src/Parsers/ParserExplainQuery.cpp:783
- `Cost` — the cost of the whole join subtree under this step, which is the value the optimizer
 minimizes when it compares candidate join orders. The cost of a join is its estimated number of
 matched row pairs, `<selectivity> * <left_rows> * <right_rows>`, plus the cost of its inputs.
- `Selectivity` — the estimated fraction of the Cartesian product of the two sides that survives
 the join condition. It is derived from the number of distinct values (NDV) of the join keys:
 a key equality keeps about `1 / max(NDV_left, NDV_right)` of the pairs, and the smallest
 fraction over the join conditions is used.
- `Output rows` — the estimated number of rows the join produces:
 `<selectivity> * <left_rows> * <right_rows>` for an inner join, floored at `<left_rows>` for
 `LEFT`, at `<right_rows>` for `RIGHT`, and at `<left_rows> + <right_rows>` for `FULL`, because an
 outer join keeps every row of its preserved side. When a `SEMI` or `ANTI` join takes part in the
 reordering, it is estimated as a fraction of its preserved side,
 `<preserved_rows> * min(1, <selectivity> * <other_rows>)` for `SEMI` and the remaining rows for
 `ANTI`; otherwise it uses the formula of its join kind.
- `Left` / `Right` — the estimated number of rows entering the join from each side.

and the ~~ prefix on ResultRows marks an imprecise estimate, which happens when any leaf of the subtree had no statistics.

A worked example: two tables of 100 rows each, joined on a column with 100 distinct values (so NDV = 100 on both sides):

 text
 
 
│ Cost: estimated 100.00
│ Selectivity: estimated (NDV) 0.01
│ Output rows: estimated 100.00
│ Left: rows estimated 100.00
│ Right: rows estimated 100.00

0.01 = 1/100 is the selectivity, 0.01 * 100 * 100 = 100 is the output row count, and 100 is also the cost (the matched-pair count) because the inputs are free.

Where the estimates are not used

This is worth being explicit about, because people assume the estimate drives everything.

The join-order optimizer’s cost model is the primary consumer. The same estimate is also handed to the physical hash join as a hint for how much to preallocate:

 cpp
 
 
// src/Processors/QueryPlan/JoinStepLogical.cpp:2596
 if (join_step->right_relation.estimated_rows)
 join_step->join_algorithm_params->rhs_size_estimation = join_step->right_relation.estimated_rows;

and the same numbers are cached: a hash table built from a given subtree and a given set of key columns is remembered with its measured row count, and that measurement is fed back into the next query’s estimate:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:550
 std::optional<size_t> num_rows_from_cache = graph.context->statistics_context.getCachedHint(node);
 if (graph.context->join_settings.use_hash_table_stats_for_join_reordering && num_rows_from_cache
 && (!stats.estimated_rows || num_rows_from_cache.value() < stats.estimated_rows.value()))
 {
 /// A measured row count beats statistics: take the minimum and mark it a precise cache value.
 stats.estimated_rows = num_rows_from_cache;
 stats.imprecise_estimate = false;
 stats.source = RowEstimateSource::HashTableCache;
 }

That last snippet is the real feedback loop: a measured row count replaces a modelled one, and the next query’s plan is better because of it. The setting that turns it on is use_hash_table_stats_for_join_reordering, on by default since 26.1.

Getting better numbers

The estimate is only as good as the statistics underneath it. The knobs:

 sql
 
 
-- Turn on column statistics for the joined columns.
ALTER TABLE t1 MATERIALIZE STATISTICS ALL;

-- Check what the optimizer believes about a table.
SELECT * FROM system.columns
WHERE table = 't1' AND column = 'id';

 sql
 
 
-- Statistics are used by default; turn them off to see the difference.
SELECT * FROM a JOIN b ON a.id = b.id SETTINGS use_statistics = 0;

The diagnostic the optimizer itself emits is the most useful one — if a relation has no column statistics, the log says so by name:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoin.cpp:981
 "Join order optimization uses imprecise row count estimates derived from the primary index "
 "because the following relation(s) have no column statistics available for join reordering: {}. "
 "The chosen join order may be suboptimal. Consider creating column statistics for the joined tables "
 "(for example, `ALTER TABLE <table> MATERIALIZE STATISTICS ALL`) and enabling the 'use_statistics' setting",

Trade-offs

The model is one formula long, and that is the point. 1/max(NDV) is a crude estimator: it assumes uniform distribution of keys, ignores correlation between two key columns, ignores the actual overlap of the two key sets, and ignores the physical layout. A real optimizer would use histograms and intersection estimates. ClickHouse trades that accuracy for a cost model that is fast enough to call for every join in every query — the whole estimate is a handful of floating-point operations per candidate pair.

The fallbacks are conservative on purpose. When the NDV is unknown, the model does not use 1/row_count as if it were measured; it marks the estimate unreliable and switches to the FK→PK heuristic. Under-estimating selectivity makes a join look cheaper than it is, which is the dangerous direction; the model’s fallbacks are arranged so that a missing statistic never makes a join look free.

Statistics are a maintenance cost. They are stored per part, they must be merged on part merges, they must be rebuilt after a ALTER, and they are cached in memory. The use_statistics setting exists because for some workloads the modelling error is larger than the benefit.

The feedback loop is the real win. The hash-table statistics cache turns the optimiser from “guessing from sketches” into “remembering what actually happened”, for the exact subtree-and-key combination that was measured.

Optimizer on Opensource internals

ClickHouse Searches Join Orders with Dynamic Programming

The memo

The one function they all share

DPsize: enumerate everything

DPhyp: enumerate only connected subsets

DPsub: connected components, and outer joins

Outer joins in DPsub

Conflict detectors

The budget and the fallback chain

Choosing an algorithm

Trade-offs

ClickHouse Reorders Joins by Turning the Join Tree into a Graph

The switch

Building the graph

The shape of a graph

Outer joins: the restriction that makes reordering legal

Transitive predicates

The greedy search

Rebuilding the plan

What it buys you, and what it costs

ClickHouse Estimates Join Cardinality from Distinct-Value Counts

Where the numbers come from

From statistics to a relation estimate

Aggregation subqueries

Selectivity

The cardinality formula

Outer joins

Semi and anti joins

NDV propagation through the join tree

Reading the numbers in EXPLAIN

Where the estimates are not used

Getting better numbers

Trade-offs