Joins 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's Merge Join Walks Two Sorted Streams and Skips Whole Runs

Jay Hubbert — Thu, 22 Oct 2026 09:00:00 +0000

TL;DR: A merge join needs no hash table and no right side in memory — it needs both sides sorted. ClickHouse sorts them, then walks two cursors in lockstep. The interesting part is not the comparison but the skipping: one fused virtual call reports both the order of two rows and how far the run of lesser rows extends, so a whole group of equal keys is consumed in one step.

The hash join is the default because it is fast when the right side fits in memory. But it has a hard ceiling: the entire right table, every column of it, has to be resident. When it does not fit, the alternatives are a spilling hash join or a merge join — and the merge join is the one that streams.

A merge join’s contract is simple: if both inputs are sorted by the join key, the join is a linear walk. Two cursors, each pointing at the current row; compare the keys; whichever side is smaller can be skipped entirely. The result is a streaming join with O(1) memory beyond the two blocks in flight.

That contract has a price — the inputs have to be sorted — and the whole implementation is about paying that price as cheaply as possible, and about the awkward fact that a merge join can only be parallelised if you first shuffle.

 sql
 
 
SELECT l.id, r.payload
FROM left_table AS l
FULL JOIN right_table AS r ON l.id = r.id
SETTINGS join_algorithm = 'full_sorting_merge';

The shape of the execution, with the two cursors walking towards each other:

 text
 
 
 LEFT input (sorted by id) RIGHT input (sorted by id)
 +----------------------+ +----------------------+
 | 1 2 3 4 5 6 7 | | 2 4 4 6 8 9 |
 +----------------------+ +----------------------+
 ^cursor ^cursor
 | |
 | compareTrackAt: "how far does the run of lesser rows go?" |
 +----------------> 2 <--------------------+
 |
 v equal key: the two runs are cross-joined
 left rows [2] x right rows [2]
 left rows [4] x right rows [4, 4]

 result (index maps, then gathered):
 +------------------------------------------+
 | (1, defaults) (2, r2) (4, r4a) (4, r4b) |
 | (5, defaults) (6, r6) (7, defaults) ... |
 +------------------------------------------+

The join object is a dummy

The first surprise is that the object representing the join in the query plan does nothing at all:

 cpp
 
 
// src/Interpreters/FullSortingMergeJoin.h:20
/// Dummy class, actual joining is done by MergeTransform
class FullSortingMergeJoin : public IJoin
{
public:
 explicit FullSortingMergeJoin(std::shared_ptr<TableJoin> table_join_, SharedHeader & right_sample_block_,
 int null_direction_ = 1, bool is_parallel_ = false)
 : table_join(table_join_)
 , right_sample_block(right_sample_block_)
 , null_direction(null_direction_)
 , is_parallel(is_parallel_)
 {

It cannot even accept data:

 cpp
 
 
// src/Interpreters/FullSortingMergeJoin.h:61
 bool addBlockToJoin(const Block & /* block */, size_t /* num_rows */, JoinBuildContext /* context */) override
 {
 throw Exception(ErrorCodes::LOGICAL_ERROR, "FullSortingMergeJoin::addBlockToJoin should not be called");
 }

All it carries is the shape of the join and one interesting bit of state: the pipeline shape. A hash join is “fill the right side first, then probe”; a merge join needs both sides running at once, so it declares a Y-shaped pipeline:

 cpp
 
 
// src/Interpreters/FullSortingMergeJoin.h:176
 /// Left and right streams have the same priority and are processed simultaneously
 JoinPipelineType pipelineType() const override { return JoinPipelineType::YShaped; }

The real engine is MergeJoinTransform, a merging processor with two input ports. Before it can run, the planner has to make both inputs sorted.

The planner sorts both sides

When the physical join step is built and the algorithm is a merge join, the planner inserts a full sort on each side:

 cpp
 
 
// src/Processors/QueryPlan/JoinStepLogical.cpp:1697
 auto add_sorting = [&] (QueryPlan::Node *& node, const Names & key_names, JoinTableSide join_table_side)
 {
 SortDescription sort_description;
 sort_description.reserve(key_names.size());
 for (const auto & key_name : key_names)
 sort_description.emplace_back(key_name);

 auto sorting_step = std::make_unique<SortingStep>(
 node->step->getOutputHeader(), std::move(sort_description), 0 /*limit*/, sort_settings, true /*is_sorting_for_merge_join*/);
 sorting_step->setStepDescription(fmt::format("Sort {} before JOIN", join_table_side), max_step_description_length);
 node = &nodes.emplace_back(QueryPlan::Node{std::move(sorting_step), {node}});
 };

Two SortingSteps, one per side, both flagged is_sorting_for_merge_join. That flag matters later: it tells the optimisers that this sort exists only to feed the merge join, so it must not be treated as an ordering the user asked for.

If a side comes out of the sort with more than one stream, the pipeline builder merges them back into one sorted stream, because the merge join takes exactly one input per side:

 cpp
 
 
// src/QueryPipeline/QueryPipelineBuilder.cpp:390
 else if (left->getNumStreams() != 1 || right->getNumStreams() != 1)
 {
 /// `MergeJoinTransform` below takes exactly one input per side. The streams are already sorted by the
 /// join keys, so a sorted merge on those keys preserves the order it requires.
 auto merge_to_single_sorted_stream = [&](std::unique_ptr<QueryPipelineBuilder> & pipeline, const Names & key_names)
 {
 if (pipeline->getNumStreams() <= 1)
 return;

 SortDescription sort_description;
 sort_description.reserve(key_names.size());
 for (const auto & key_name : key_names)
 sort_description.emplace_back(key_name);

 auto transform = std::make_shared<MergingSortedTransform>(
 pipeline->getSharedHeader(),
 pipeline->getNumStreams(),
 sort_description,
 max_block_size,
 /*max_block_size_bytes=*/ 0,
 /*max_dynamic_subcolumns=*/ std::nullopt,
 SortingQueueStrategy::Default);

Before sorting: filter with a set

There is an optimisation that runs before the sort, and it is the one that makes merge joins practical on skewed data. If one side is small, build a hash set of its keys and filter the other side with it:

 cpp
 
 
// src/Processors/QueryPlan/JoinStepLogical.cpp:1743
 if (join_settings.max_rows_in_set_to_optimize_join > 0 && join_type_allows_filtering && has_non_const_keys)
 {
 auto * left_set = add_create_set(left_node, join_clause.key_names_left, JoinTableSide::Left);
 auto * right_set = add_create_set(right_node, join_clause.key_names_right, JoinTableSide::Right);

 if (isInnerOrLeft(join_kind))
 right_set->setFiltering(left_set->getSet());

 if (isInnerOrRight(join_kind))
 left_set->setFiltering(right_set->getSet());
 }

The set is built while the stream is being read — the CreatingSetsOnTheFly transform inserts into it as blocks arrive — and the other side is filtered against it once it is complete. If the set turns out to be too big, the whole thing is abandoned and the join proceeds unfiltered:

 cpp
 
 
// src/Processors/Transforms/CreateSetAndFilterOnTheFlyTransform.cpp:114
 if (chunk.getNumRows())
 {
 Columns key_columns = getColumnsByIndices(chunk, key_column_indices);
 bool limit_exceeded = !set->insertFromColumns(key_columns);
 if (limit_exceeded)
 {
 auto prev_state = set->state.exchange(SetWithState::State::Suspended);
 /// Print log only after first state switch
 if (prev_state == SetWithState::State::Creating)
 {
 LOG_DEBUG(log, "{}: set limit exceeded, give up building set, after reading {} rows and using {}",
 getDescription(), set->getTotalRowCount(), formatReadableSizeWithBinarySuffix(set->getTotalByteCount()));
 }

The filter side checks the state before filtering, and only filters if the set actually reached the “finished” state:

 cpp
 
 
// src/Processors/Transforms/CreateSetAndFilterOnTheFlyTransform.cpp:178
 bool can_filter = set && set->state == SetWithState::State::Finished;
 if (!can_filter)
 stat.consumed_rows_before_set += chunk.getNumRows();

 if (can_filter && chunk.getNumRows())
 {
 auto key_columns = getColumnsByIndices(key_sample_block, chunk, key_column_indices);
 ColumnPtr mask_col = set->execute(key_columns, false);

This is a “semi-join reduction” and it is the difference between sorting and comparing a hundred million rows and sorting and comparing a hundred thousand. The setting that controls it is off by default:

 cpp
 
 
// src/Core/Settings.cpp:4537
 DECLARE(UInt64, max_rows_in_set_to_optimize_join, 0, R"(
Maximal size of the set to filter joined tables by each other's row sets before joining.

Possible values:

- 0 — Disable.
- Any positive integer.
)", 0, \
 {"24.1", 100000, 0, "Disable join optimization as it prevents from read in order optimization"}) \

It was disabled by default in 24.1 because the set has to be built before the filter can run, which blocks the “read in order” optimisation — a MergeTree table read in primary-key order can no longer stream into the join.

The cursor

Each side of the join is a FullMergeJoinCursor: a chunk, a position, and the key columns pre-processed. The pre-processing matters — LowCardinality is expanded and Nullable is split into a null map plus a nested column, so the comparison loop never has to deal with either:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:470
 const auto & all_columns = current_chunk.getColumns();
 for (size_t i : key_indices)
 {
 auto column = all_columns.at(i);
 column = column->convertToFullColumnIfLowCardinality();
 ColumnPtr null_map = nullptr;
 if (const auto * column_nullable = checkAndGetColumn<ColumnNullable>(column.get()))
 {
 null_map = column_nullable->getNullMapColumnPtr();
 column = column_nullable->getNestedColumnPtr();
 }
 null_maps.push_back(std::move(null_map));
 sort_columns.push_back(std::move(column));
 }

The fused comparison

Here is the mechanism the whole join is built around. A merge join does not just need to know which row is smaller; it needs to know how many consecutive rows on the smaller side are also smaller. If the left side has a thousand rows with key 5 and the right side’s current key is 7, all thousand left rows are smaller, and the join can consume all thousand at once.

The naive implementation compares two rows, and then separately searches for the end of the run — two passes over the same data. ClickHouse fuses them into one virtual call, and the contract is spelled out on the column interface:

 cpp
 
 
// src/Columns/IColumn.h:547
 /** Compares (*this)[n] and rhs[m] like compareAt, additionally reporting how far the run of
 * lesser values on the lesser side extends. Returns 0 if the values are equal; -N if rows
 * [n, n + N) of *this are all less than rhs[m]; +N if rows [m, m + N) of rhs are all less
 * than (*this)[n]. N >= 1 and the runs are maximal.
 *
 * PRECONDITION: the tail of the lesser column (starting at n, respectively m) is sorted
 * ascending consistently with compareAt under the same nan_direction_hint; the run end is
 * found by galloping (findEqualRangeEndAssumeSorted), which relies on it.
 *
 * The main reason for the function is to fuse the comparison and the run search into one
 * virtual call. IColumnHelper implements it for all concrete columns with devirtualized
 * compareAt probes; ColumnVector, ColumnDecimal and ColumnFixedString specialize it to probe
 * raw data with the per-call setup (data pointers, the Decimal scale dispatch) hoisted out
 * of the run search.
 */
 [[nodiscard]] virtual Int64 compareTrackAt(size_t n, size_t m, const IColumn & rhs, int nan_direction_hint) const = 0;

The run search itself is a galloping search, preceded by a short linear probe — because short runs are the common case and a binary search on a run of length two is pure overhead:

 cpp
 
 
// src/Columns/findEqualRangeEndAssumeSorted.h:94
/** Returns the end (exclusive) of the run of values equal to the value at `begin`, within the sorted
 * range `[begin, end)`. The predicate `equals(i)` must report whether the value at row `i` equals the
 * value at `begin`.
 *
 * The search first does a short linear probe, which is cheap for the common case of short,
 * high-cardinality runs. If the run extends past that probe, it switches to galloping (an exponential
 * probe) followed by a binary search, so for a long run it issues only O(log run) calls to `equals`
 * instead of O(run).
 *

And the shared tail is deliberately ALWAYS_INLINE, with a measured reason:

 cpp
 
 
// src/Columns/findEqualRangeEndAssumeSorted.h:116
/** Shared tail of compareTrackAt (see IColumn::compareTrackAt): given `compare_result` for lhs[n] vs
 * rhs[m], find the end of the run of lesser rows on the lesser side by galloping. The predicate
 * is_less(row) must report lhs[row] < rhs[m], and is_greater(row) must report lhs[n] > rhs[row];
 * the sorted-tail precondition of compareTrackAt applies to the probed side.
 *
 * ALWAYS_INLINE: the merge joins call compareTrackAt once per loop iteration; leaving this as a
 * separate call behind the virtual one costs ~10% on interleaved short-run keys.
 */

Ten percent, for one ALWAYS_INLINE. That is the kind of number that tells you the loop is the bottleneck.

The merge loop uses it like this:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:660
 while (left_cursor.isValid() && right_cursor.isValid())
 {
 lpos = left_cursor.getRow();
 rpos = right_cursor.getRow();

 /// Compare the first key column once: a nonzero result decides the whole tuple
 /// comparison and carries the run of lesser rows that can be skipped at once.
 FirstKeyCompare first_key = trackCursorsFirstKey(left_cursor, right_cursor, null_direction_hint);
 cmp = first_key.cmp != 0 ? first_key.cmp : compareCursors(left_cursor, lpos, right_cursor, rpos, null_direction_hint, /*from_key=*/ 1);

Note the structure: the first key column is compared with compareTrackAt, which both decides the order and measures the run. Only if the first columns are equal does the code walk the remaining key columns — and then it starts at column 1, because column 0 has already been compared.

Equal runs

When the keys are equal, the join has to emit the cross product of the two equal ranges (for an ALL join). The end of an equal range is found with a per-column search:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:222
size_t ALWAYS_INLINE nextDistinct(FullMergeJoinCursor & impl)
{
 chassert(impl.isValid());
 const size_t start_pos = impl.getRow();

 /// Find the end of the run of rows that share the same (multi-column) key, starting at start_pos.
 const size_t run_end = impl.key_runs.findRunEnd(
 start_pos,
 impl.rows,
 [&](size_t i, size_t from, size_t bound)
 {
 const auto * nm = getNullMapData(impl.null_maps[i]);
 const bool ref_is_null = nm && (*nm)[from] != 0;

 size_t column_run_end = bound;
 if (nm)
 column_run_end
 = findEqualRangeEndAssumeSorted(from, column_run_end, 16, [&](size_t row) { return ((*nm)[row] != 0) == ref_is_null; });

 if (!ref_is_null)
 column_run_end = impl.sort_columns[i]->getEqualRangeEndAssumeSorted(from, column_run_end, 1);

 return column_run_end;
 });
 impl.pos = run_end;
 return run_end - start_pos;
}

key_runs is a SortedKeyRuns, which remembers the run found for each key prefix, so a multi-column key search does not restart from column 0 every time:

 cpp
 
 
// src/Columns/findEqualRangeEndAssumeSorted.h:168
/** Same result as `findKeyRangeEndAssumeSorted`, for callers that search the runs of one range one after another.
 * Remembers the last run found for each key prefix: a search from a row inside it ends at the same row, so a column
 * is searched again only when the search leaves its prefix's run. Call `reset` when the columns change, or when `end`
 * changes and the next search may start before the previous `end`.
 */
class SortedKeyRuns

The output is an index map, not a copy

The join does not copy rows as it goes. It computes, for each side, an array of row indices into the current block, and the result block is built at the end by gathering through those indices:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:195
ColumnPtr indexColumn(const ColumnPtr & column, const DataTypePtr & type, const PaddedPODArray<UInt64> & indices)
{
 auto new_col = column->cloneEmpty();
 new_col->reserve(indices.size());
 for (size_t idx : indices)
 {
 /// Rows where a default should be inserted have index == size. Fill them through the
 /// data type: types whose default is not all-zero (e.g. Enum, whose default is the
 /// first member) must not get a raw zero. Every non-joined-row fill in this file goes
 /// through the data type for the same reason.
 if (idx < column->size())
 new_col->insertFrom(*column, idx);
 else
 type->insertDefaultInto(*new_col);
 }
 return new_col;
}

An index equal to the column’s size means “this row did not match”; the default is filled in. Note that the index map doubles as the filter: for an INNER join, the unmatched left rows simply never appear in the map.

For an ALL join the index maps are built as a cross product of the two equal ranges:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:676
 bool all_fit_in_block = !max_block_size || std::max(left_map.size(), right_map.size()) + lnum * rnum <= max_block_size;
 bool have_all_ranges = left_cursor.isValid() && right_cursor.isValid();
 if (all_fit_in_block && have_all_ranges)
 {
 /// fast path if all joined rows fit in one block
 for (size_t i = 0; i < rnum; ++i)
 {
 addRange(left_map, lpos, left_cursor.getRow());
 addMany(right_map, rpos + i, lnum);
 }
 }

lnum * rnum is the size of the cross product. If it does not fit in one block, the join switches to the “accumulate and cross” mode, where the equal ranges are buffered in AllJoinState and the product is walked incrementally:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:790
 if (all_join_state)
 {
 chassert(cursors.size() == 2);
 /// Accumulate blocks with same key in all_join_state
 for (size_t i = 0; i < 2; ++i)
 {
 if (cursors[i].isValid() && all_join_state->keys[i].equals(cursors[i]))
 {
 size_t pos = cursors[i].getRow();
 size_t num = nextDistinct(cursors[i]);
 stat.matched_rows.side(i) += num;
 all_join_state->addRange(i, cursors[i].getCurrent().clone(), pos, num);
 }
 }

The `ANY` case has to remember the previous block

An ANY join emits one row per matching key — but the match may be in the next block of the other side. When the left cursor runs out, the join has to remember the key it was on and the right row it matched, so the next call can complete the match:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.h:67
/// Remembers previous key if it was joined in previous block
class AnyJoinState : boost::noncopyable
{
public:
 void set(size_t source_num, const FullMergeJoinCursor & cursor);
 void setValue(Chunk value_);

 void reset(size_t source_num);

 bool empty() const;

 /// current keys
 JoinKeyRow keys[2];

 /// for LEFT/RIGHT join use previously joined row from other table.
 Chunk value;

JoinKeyRow is a materialised copy of the key columns of one row — one row of one-row columns — because the block it came from may be gone by the time the state is checked.

ASOF

ASOF is the odd one out: it is not an equality join but an inequality join — “the closest row on the right whose ASOF column is at most mine”. The merge join implements it by walking the right side and remembering the last row that satisfied the inequality:

 cpp
 
 
// src/Processors/Transforms/MergeJoinTransform.cpp:845
std::optional<MergeJoinAlgorithm::Status> MergeJoinAlgorithm::handleAsofJoinState()
{
 if (strictness != JoinStrictness::Asof)
 return {};

 if (!cursors[1].fullyCompleted())
 return {};

The right side has to be complete before an ASOF match can be decided, because the closest match might be further down the right stream. So the ASOF path buffers the whole right side’s relevant state — it is the one strictness that cannot be fully streaming.

Parallelism: sharding by hash

A single merge join is single-threaded: two cursors, one thread. To use several threads, the join has to be sharded, and the only way to shard a merge join is to shuffle the rows by a hash of the join key so that equal keys end up in the same shard on both sides:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoinByShards.cpp:518
/// Shard a `parallel_full_sorting_merge` join into independent per-shard merge joins by the hash of the
/// join keys.
///
/// Unlike `optimizeJoinByShards` above (which shards by primary-key ranges and only works when both sides
/// read from MergeTree in order), this works on any unsorted input: each side's pre-join full
/// `SortingStep` is switched to scatter the rows by the hash of the join keys into independent partitions
/// and sort each partition (one sorted stream per shard), and the join is executed shard-by-shard

The rewrite is guarded by a surprising number of conditions, and the comments explain why each one exists. The first is that only the parallel variant may be sharded — because the sharded result is unordered, and silently changing the ordering of a query that asked for full_sorting_merge would be wrong:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoinByShards.cpp:548
 /// Only shard when `parallel_full_sorting_merge` was the algorithm actually selected. Both
 /// algorithms build the same `FullSortingMergeJoin`, so `join_algorithm` membership is not
 /// enough: with `full_sorting_merge,parallel_full_sorting_merge` the priority list selects plain
 /// `full_sorting_merge` and the parallel variant is an unreached fallback, so the sharded
 /// (unordered) rewrite must not fire. `FullSortingMergeJoin::isParallel` carries the selected
 /// algorithm over from `chooseJoinAlgorithm`.

The second is ASOF, whose trailing key is an inequality key, so rows with equal equality keys but different ASOF values would land in different shards and the closest match could be missed.

The third is the deadlock. This is the most interesting comment in the file:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoinByShards.cpp:572
 /// An already-sorted side (`FinishSorting`: a MergeTree read in order, or any input
 /// recognized as pre-sorted) must NOT be scattered, tempting as an order-preserving scatter
 /// is. It can deadlock: a `ScatterByPartitionTransform` does not consume new input until all
 /// partition chunks of the previous one are pushed, while its consumers (per-partition
 /// `MergingSortedTransform`s, per-shard `MergeJoinTransform`s) wait for a chunk of one
 /// specific input each. Two such scatters then form a circular wait - A blocked pushing to
 /// shard `i` whose merge waits on B, B blocked pushing to shard `j` whose merge waits on A
 /// (seen as `Logical error: Pipeline stuck` in the AST fuzzer). The full-sort path is immune
 /// while every shard lane is demanded: a sleeping lane never starts draining its input.

A ScatterByPartitionTransform will not read the next chunk until it has pushed all partitions of the current one; the consumers wait for one specific partition each; two such scatters deadlock on each other. The Full sort path is immune because every shard lane is demanded at once.

And the fourth is the hash/equality consistency of the key type. Float64 breaks it: -0.0 == +0.0 but they hash differently, and NaN == NaN in ClickHouse’s comparison but not in a hash:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/optimizeJoinByShards.cpp:599
 /// Do not shard when a join key is (or contains) a type whose hash-based shard selection
 /// is not consistent with the merge-join `compareAt` - floating-point (`-0.0` == `+0.0`,
 /// NaN == NaN), `JSON`/`Object`, or `Dynamic` - so equal keys could land in different
 /// shards and the match would be lost (see `keyTypeBreaksHashSharding`). If a key
 /// column cannot be found to check its type, be conservative and skip sharding as well.

This is a real class of bug that only shows up in parallel merge joins: single-threaded, the comparison is exact; sharded, the hash decides.

The other way to parallelise: primary-key ranges

The most recent addition (enabled by default in 26.10) shards the join by primary key range instead of by hash, which needs no shuffle at all:

 cpp
 
 
// src/Core/Settings.cpp:3142
 DECLARE(Bool, query_plan_join_shard_by_pk_ranges, true, R"(
Execute a JOIN of two MergeTree tables as independent joins over primary-key ranges when the join keys contain a prefix of the primary key of both tables. Both tables are split into the same ranges by the values of that prefix (the same way `FINAL` splits parts into non-intersecting layers), so equal keys land in the same range, and each range is joined on its own thread.

For `full_sorting_merge` and `parallel_full_sorting_merge`, this replaces a single-threaded merge join over both tables with one streaming merge join per range, running in parallel, which is typically several times faster and uses several times less memory.

The trick is that the ranges are cut by the same key prefix on both sides, so a key can only match inside its own range — and each range’s join is a plain, independent merge join. No hash, no shuffle, no deadlock.

Trade-offs

What the merge join buys:

O(1) memory. Only the two current blocks are in flight. A join over a right table that does not fit in memory is possible.
No hash table, no hash collisions, no hashed fallback.
The comparison work is amortised over runs. One compareTrackAt call can consume thousands of rows.

What it costs:

Both sides must be sorted. The sort is the dominant cost unless the data is already ordered — and a sort is O(n log n) with a memory cost of its own, which can exceed the memory a hash join would have used.
It is single-threaded by construction. Parallelism needs either a shuffle (hash sharding) or a range split (primary-key ranges), and both have sharp edges: the float/NaN key hazard, the scatter deadlock, and the unordered output.
The join keys must have compatible types. String and Nullable(String) cannot be merged, and the check happens at plan time.
ASOF is not streaming. The right side must be complete before a match can be decided.
The set-based pre-filter is off by default, because it breaks the read -in-order optimisation.

Wrapping up

The one thing to remember: a merge join is a sorted join. The algorithm is trivial — two cursors, compare, advance — and all the engineering is in the skipping (compareTrackAt), in the sort that has to come first, and in the sharding that has to happen afterwards.

The part people get wrong: the merge join does not need the right side in memory, but it does need it sorted, and sorting is not free. A merge join on unsorted data is usually slower than a hash join, not faster.

What to go do about it: if you have a large join that is spilling or failing on memory, look at whether the tables are ordered by the join key. If they are, full_sorting_merge with query_plan_join_shard_by_pk_ranges gives you a parallel, streaming join with no shuffle. If they are not, and the right side is small enough to filter with a set, turn on max_rows_in_set_to_optimize_join and measure — the set is built while the stream is read, so it costs a hash table, not a second pass.

ClickHouse's Hash Join Stores the Right Table as 64-bit Row Words

Jay Hubbert — Thu, 22 Oct 2026 09:00:00 +0000

TL;DR: A hash join’s hash table does not hold the joined data. It holds one 64-bit word per key, encoding (block_no, row_no) of a row in the right table’s stored columnar blocks — with bit 63 tagging whether the word is the row itself or a pointer to an arena node holding the duplicates. The probe loop records those words; a separate gather kernel turns them back into columns with memcpy and a 32-row software prefetch.

Every join needs the same thing: given a key from the left side, find the right-side rows that carry that key. The textbook hash join puts the right table’s rows into the hash table. That works, but it means the joined columns are copied out of their columnar form, into a hash table’s cell layout, and then copied back out again into the result block. For a wide right table with a narrow key, that is two extra passes over the data.

ClickHouse takes the opposite route. The right table stays where it is — as a list of columnar blocks — and the hash table stores only an address. The address is one UInt64. Everything else in the join machinery is built on top of that one decision.

 sql
 
 
SELECT l.id, r.payload
FROM left_table AS l
JOIN right_table AS r ON l.id = r.id;

The whole join, in one picture:

 text
 
 
 BUILD PHASE (the right side, streamed once)

 right block 0 right block 1 right block 2
 +-----------+ +-----------+ +-----------+
 | col a | | col a | | col a |
 | col b | | col b | | col b |
 +-----------+ +-----------+ +-----------+
 | | |
 +---------+--------+---------+--------+
 v v
 stored_columns: [blk0][blk1][blk2] arena: dup nodes, string keys

 hash table (key -> one 8-byte word)
 +------------+------------------------------+
 | key 42 | 0x8000_0000_0000_0017 | <- inline RowRef
 | key 43 | 0x0000_7fff_aabb_cdde | <- pointer to Batch node
 +------------+------------------------------+

 PROBE PHASE (the left side, streamed)

 left block words recorded, one per output row
 +-----------+ +---------------------------------+
 | id = 42 | -- lookup ------> | 0x8000_0000_0000_0017 |
 | id = 99 | -- lookup ------> | 0x0000_0000_0000_0000 (no hit) |
 +-----------+ +---------------------------------+

 GATHER PHASE (the words become columns)

 words --> for each word: (block_no, row_no) --> memcpy from the stored
 block, with a prefetch 32 rows ahead

The word

The address is RowRef, and it is exactly eight bytes, which matters because it is the hash table’s cell payload:

 cpp
 
 
// src/Interpreters/RowRefs.h:43
struct RowRef
{
 static constexpr UInt32 INLINE_FLAG = 0x80000000u;
 static constexpr UInt32 BLOCK_NO_MASK = 0x7FFFFFFFu;
 static constexpr UInt64 ENCODED_INLINE_FLAG = 1ull << 63;

 UInt32 row_no = 0;
 UInt32 block_no = 0; /// includes INLINE_FLAG in the MSB

 RowRef() = default;
 RowRef(size_t block_no_, size_t row_no_)
 : row_no(static_cast<UInt32>(row_no_))
 , block_no(static_cast<UInt32>(block_no_) | INLINE_FLAG)
 {

The two halves are a block number — an index into the join’s list of stored right-hand blocks — and a row number within that block. Bit 31 of the block number is not part of the block number: it is the inline flag. When it is set, the encoded word is the row reference. When it is clear, the word is either zero (the “no match” marker) or a pointer to a list of duplicates.

 cpp
 
 
// src/Interpreters/RowRefs.h:96
/// Mapped value of MapsAll join hash maps (ALL JOINs / non-unique keys): a tagged 8-byte word.
/// - bit 63 is 1: the key has exactly one row so far; the word IS the encoded RowRef (inline).
/// - bit 63 is 0 and the word is not 0: a pointer (bits 47..0) to an arena-allocated `Batch` node,
/// with the duplicate count packed into bits 62..48 (saturating; see COUNT_SAT). The count lets
/// the probe loop read `rows` straight from the cell word without dereferencing the node.

The point of the inline flag is that the common case — a key that matches exactly one right row — costs no extra allocation at all. The hash table cell is 8 bytes either way; only keys with duplicates pay for an arena node.

Duplicates live in an arena node

For an ALL join, one key can match many right rows. Those rows are chained into a Batch node allocated from the join’s arena, and the cell word points at the first one:

 cpp
 
 
// src/Interpreters/RowRefs.h:113
 /// A single 64-byte node. The cell word always points at the FIRST ("cell") node of a key.
 /// `head` and the local slots are one contiguous `refs` array (refs[0] is the head) so the
 /// iterator can walk them as a single run without out-of-array pointer arithmetic.
 ///
 /// Cell node, unchained (2..7 rows): `refs[0]` holds the first row, `refs[1 .. size-1]` the rest;
 /// `size == total_rows`; no pointers.
 /// Cell node, chained (>= 8 rows): `refs[0 .. 5]` hold the 6 oldest rows; `refs[SLOTS]` (= refs[6])
 /// is a raw pointer to the NEWEST overflow node; `size == 6 != total_rows`.

Seven rows fit inline in the 64-byte node (one head plus six slots); the eighth row turns the node into a chain head. The count of duplicates is packed into bits 48..62 of the cell word, so the probe loop can ask “how many rows does this key have?” without dereferencing anything:

 cpp
 
 
// src/Interpreters/RowRefs.h:181
 size_t rows() const
 {
 if (isInline())
 return 1;
 const UInt32 count = static_cast<UInt32>((word >> COUNT_SHIFT) & COUNT_SAT);
 if (count != COUNT_SAT)
 return count;
 return asBatch()->total_rows;
 }

The pointer field is 48 bits, and the code explains at length why that is safe on current Linux and what would happen if it were not:

 cpp
 
 
// src/Interpreters/RowRefs.h:81
/// Thrown when an arena pointer does not fit in the low 48 bits of a RowRefList word, which would
/// make the pointer+count packing ambiguous. Cannot happen on Linux x86-64/aarch64 today: even with
/// 5-level paging (`CONFIG_X86_5LEVEL`, 57-bit VA) or arm64 52-bit LVA, the kernel hands out
/// mappings above the 47-bit boundary only when the mmap address hint explicitly requests them,

So a hash table cell is: a key (whatever width the key needs) plus 8 bytes. For an INNER JOIN on a UInt64 key that is 16 bytes of payload per distinct key, and the joined columns are not in the table at all.

Choosing the map

Which map flavour runs is decided once, from the types of the key columns, before a single row is read. chooseMethod is a small decision tree over the key columns:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:427
 /// If there is one numeric key that fits in 64 bits
 if (keys_size == 1 && key_columns[0]->isNumeric())
 {
 size_t size_of_field = key_columns[0]->sizeOfValueIfFixed();
 /// The loop above bails out before assigning `key_sizes` for a `LowCardinality` column.
 key_sizes[0] = size_of_field;
 if (size_of_field == 1)
 return Type::key8;
 if (size_of_field == 2)
 return Type::key16;
 if (size_of_field == 4)
 return Type::key32;
 if (size_of_field == 8)
 return Type::key64;
 if (size_of_field == 16)
 return Type::keys128;
 if (size_of_field == 32)
 return Type::keys256;
 throw Exception(ErrorCodes::LOGICAL_ERROR, "Numeric column has sizeOfField not in 1, 2, 4, 8, 16, 32.");
 }

Multiple key columns are interesting: if all of them are fixed-width and together fit in 4, 8, 16 or 32 bytes, the columns are packed into one integer and the hash table has a single integer key:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:448
 /// If the keys fit in N bits, we will use a hash table for N-bit-packed keys
 if (all_fixed && keys_bytes <= 4)
 return Type::keys32;
 if (all_fixed && keys_bytes <= 8)
 return Type::keys64;
 if (all_fixed && keys_bytes <= 16)
 return Type::keys128;
 if (all_fixed && keys_bytes <= HashJoin::max_packed_keys_bytes)
 return Type::keys256;

The packing itself is a hashing method, not a join-specific hack:

 cpp
 
 
// src/Interpreters/HashJoin/KeyGetter.h:221
template <typename Value, typename Mapped> struct KeyGetterForTypeImpl<HashJoin::Type::keys32, Value, Mapped>
{
 using Type = ColumnsHashing::HashMethodKeysFixed<Value, UInt32, Mapped, false, false, false, use_offset>;
};
template <typename Value, typename Mapped> struct KeyGetterForTypeImpl<HashJoin::Type::keys64, Value, Mapped>
{
 using Type = ColumnsHashing::HashMethodKeysFixed<Value, UInt64, Mapped, false, false, false, use_offset>;
};

The last resort is Type::hashed: a cryptographic hash of an unambiguously serialised tuple of values. It is correct for any key type, but it is a hash — two different keys could in principle collide, so it is only used when nothing better fits.

There are 34 map types in total, including “two level” variants (a fixed number of buckets, each with its own sub-table, to avoid a long chain of cache misses on huge tables), “range” variants (a FixedHashMap for a dense integer range), and low_cardinality_key_* variants that key on a dictionary index. All of them are listed in one macro, APPLY_FOR_JOIN_VARIANTS in src/Interpreters/HashJoin/HashJoin.h:247.

The right table itself

The right-hand blocks are kept in a std::list of stored blocks, alongside the arena that holds the duplicate nodes and the string keys:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.h:526
 struct RightTableData
 {
 Type type = Type::hashed;

 /// tab1 join tab2 on t1.x = t2.x or t1.y = t2.y
 /// =>
 /// tab1 join tab2 on t1.x = t2.x
 /// join tab2 on [not_joined(t1.x = t2.x)] and t1.y = t2.y
 std::vector<MapsVariant> maps;
 Block sample_block; /// Block as it would appear in the BlockList
 StoredBlocksList columns; /// Columns of "right" table.
 NullmapList nullmaps; /// Nullmaps for blocks of "right" table (if needed)

Note std::vector<MapsVariant> maps — one map per ON clause. A join with two disjunctive conditions gets two independent hash tables, one per clause, and the probe loop tries each in turn. This is how ClickHouse supports ON a.x = b.x OR a.y = b.y without a general-purpose join.

The build phase appends each incoming right block to that list, and this is also where the memory accounting happens:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:1046
 doDebugAsserts();
 /// Register the block and account for it while a local list still owns it: `splice` cannot throw,
 /// so `data->columns`, `data->allocated_size` and `data->rows_to_join` always describe the same set
 /// of stored blocks. Same ordering as `tryRerangeRightTableDataImpl`; a list node keeps its address.
 StoredBlocksList new_block;
 new_block.emplace_back(std::move(columns), std::move(selector), std::move(row_store));
 auto * stored_columns = &new_block.back();
 size_t data_allocated_bytes = stored_columns->allocatedBytes();
 stored_columns->block_no = data->stored_columns_index->add(stored_columns);
 data->allocated_size += data_allocated_bytes;
 data->rows_to_join += rows;
 data->columns.splice(data->columns.end(), new_block);

splice is used rather than push_back so that the list node’s address never changes: the block number is the block’s index in the list, and the index must stay valid for the lifetime of the join.

The “used” flags

For a RIGHT or FULL join, the right table must be reported at the end: rows that never matched have to be emitted with default left columns. That requires knowing, per right row, whether it was used. The flags live in a separate structure, not in the hash table, because the hash table is immutable once the build phase ends:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.h:665
 /// Right table data. StorageJoin shares it between many Join objects.
 /// Flags that indicate that particular row already used in join.
 /// Flag is stored for every record in hash map.
 /// Number of this flags equals to hashtable buffer size (plus one for zero value).
 /// Changes in hash table broke correspondence,
 /// so we must guarantee constantness of hash table during HashJoin lifetime (using method setLock)
 mutable std::shared_ptr<JoinStuff::JoinUsedFlags> used_flags;

There are three granularities: no flags at all, one flag per hash table offset (the whole key), or one flag per right row (a std::vector<std::atomic_bool> per stored block). The per-row variant is needed when a right row can be reachable through more than one key, and it is the reason the flags are atomic — the probe phase can run on several threads at once (ConcurrentHashJoin shards the probe). The relaxed ordering is enough: the flag says “some thread saw this row”, and nothing depends on which thread.

The probe does not materialise columns

Here is the part that makes the whole design pay off. The probe loop does not copy a single right-side value into the result. It records words:

 cpp
 
 
// src/Interpreters/HashJoin/AddedColumns.h:63
struct LazyOutput
{
 /// Entries share the encoding of the join hash map cell values (see RowRefs.h):
 /// 0 - default row; bit 63 set - inline encoded RowRef; otherwise - a RowRefList
 /// list word (pointer to a Batch node in the low 48 bits + row count).
 /// ASOF matches are inline encoded RowRef words too (the leaf of the sorted lookup vector).
 PaddedPODArray<UInt64> row_refs;
 size_t row_count = 0; /// Total number of rows in all refs and ref lists
 size_t hash_table_matches = 0; /// Total number of hash table matches

row_refs is a PaddedPODArray<UInt64> — one word per output row. The probe loop is a pure hash-table walk that appends words:

 cpp
 
 
// src/Interpreters/HashJoin/AddedColumns.h:231
 /// Encoded RowRef word (inline single ref, including an ASOF match) or a RowRefList
 /// list word (pointer + count).
 ALWAYS_INLINE void appendFromBlock(UInt64 ref_word)
 {
#ifndef NDEBUG
 /// `ref_word` may be an inline single ref or a list word (pointer + count); firstWord yields
 /// the head ref of either, whose block is valid for the column-structure assertion.
 checkColumns(*lazy_output.stored_columns[refWordBlockNo(RowRefList::fromWord(ref_word).firstWord())]);
#endif
 if (record_row_refs)
 lazy_output.addRef(ref_word);
 }

Because the words are recorded and not values, the same recording works for every strictness: INNER, LEFT, ANY, SEMI, ANTI, ASOF. What differs between them is only which word (or no word) is appended for a given left row. That is what the processMatch template does:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoinMethodsImpl.h:619
 else /// ANY LEFT, SEMI LEFT, old ANY (RightAny)
 {
 setUsed<need_filter>(added_columns.filter, i, added_columns.matched_rows);
 used_flags.template setUsed<join_features.need_flags, flag_per_row>(find_result);
 added_columns.appendFromBlock(firstRefWord(mapped));
 }

An ANY join appends the first word of the key’s cell; an ALL join appends the whole cell word and lets the emit kernel expand the list.

The gather kernel

The words are turned into columns by a separate pass, and this is where the memory bandwidth of the join actually goes. The kernel for fixed-width columns is a memcpy loop with a software prefetch 32 rows ahead:

 cpp
 
 
// src/Interpreters/HashJoin/gatherJoinOutputColumns.cpp:106
/// 32 rows of lead cover one source row's memory latency.
constexpr size_t look_ahead = 32;

 cpp
 
 
// src/Interpreters/HashJoin/gatherJoinOutputColumns.cpp:151
 const size_t num_refs = row_refs_end - row_refs_begin;
 for (size_t i = 0; i < num_refs; ++i)
 {
 if (i + look_ahead < num_refs)
 {
 /// Only an inline word carries a (block_no, row_number) address.
 const UInt64 ahead = row_refs_begin[i + look_ahead];
 if (refWordIsInline(ahead))
 __builtin_prefetch(source_at(ahead));
 }

 const UInt64 word = row_refs_begin[i];
 if (!word)
 {
 memcpy(out, default_pattern, stride);
 out += stride;
 continue;
 }

A zero word means “no match”, and it writes the column’s default pattern — which is not necessarily all-zero bytes, hence the deliberate indirection through the data type:

 cpp
 
 
// src/Interpreters/HashJoin/gatherJoinOutputColumns.cpp:919
/// The `stride` bytes an unmatched row of a fixed-width column writes. Held as data rather than
/// derived, because a fixed-width default is not always bitwise zero - an `Enum`'s is its first value.
/// `type` is null below a `Nullable`, where `insertDefault` fills the nested planes from the nested
/// *column*'s default instead; the two differ for an `Enum`, and `assumeNotNull` sees it.
std::vector<char> fixedDefaultPattern(const IColumn & column, const IDataType * type)
{
 MutableColumnPtr default_row = column.cloneEmpty();
 if (type)
 type->insertDefaultInto(*default_row);
 else
 default_row->insertDefault();
 const std::string_view default_bytes = default_row->getRawData();
 return {default_bytes.begin(), default_bytes.end()};
}

The stride is a compile-time constant whenever it can be, which turns the copy into a single load and a single store:

 cpp
 
 
// src/Interpreters/HashJoin/gatherJoinOutputColumns.cpp:187
template <typename F>
ALWAYS_INLINE void withStride(size_t stride, F && f)
{
 switch (stride)
 {
 case 1: f.template operator()<1>(); break;
 case 2: f.template operator()<2>(); break;
 case 4: f.template operator()<4>(); break;
 case 8: f.template operator()<8>(); break;
 case 16: f.template operator()<16>(); break;
 case 32: f.template operator()<32>(); break;
 default: f.template operator()<0>(); break;
 }
}

Some joins need no right rows at all

LEFT SEMI and LEFT ANTI never take a value from the right side: SEMI emits the left row alone if the key is present, ANTI emits it alone if the key is missing. For those, the hash table does not need a mapped value at all — it becomes a set.

That is expressed at the type level with a VoidMapped placeholder and a conditional type alias:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.h:351
 /** Different data structures, that are used to perform JOIN.
 *
 * A join whose result never contains a value taken from a right row - see `MapGetter` - does not
 * need the mapped part of a cell at all: the table only has to answer whether a key is present.
 * Such a join instantiates the maps with `VoidMapped`, which selects the set counterpart of every
 * table below, so a cell holds the key alone.
 */
 template <typename Key, typename Mapped, typename Hash>
 using JoinHashMap = std::conditional_t<std::is_same_v<Mapped, VoidMapped>, HashSet<Key, Hash>, HashMap<Key, Mapped, Hash>>;

and the choice of set maps is a policy decision with a very precise predicate:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:578
bool HashJoin::canUseSetMaps() const
{
 if (!table_join->enableJoinKeyOnlyHashTables())
 return false;

 /// A mixed join expression is evaluated against the right rows themselves.
 if (preferUseMapsAll() || table_join->getMixedJoinExpression())
 return false;

 /// `StorageJoin` reads its rows back out of the maps, both to `SELECT` from the table and for
 /// `joinGet`.
 if (table_join->isSpecialStorage())
 return false;

 if (kind != JoinKind::Left)
 return false;

 /// LEFT ANTI emits a left row only when its key is missing, and fills the right columns with
 /// defaults, so no right row is ever read whatever is selected from the right side.
 if (strictness == JoinStrictness::Anti)
 return true;

 /// LEFT SEMI emits the matched left row alone, so it qualifies when nothing of the right side
 /// besides the join keys - which are taken from the left row - is selected.
 return strictness == JoinStrictness::Semi && sample_block_with_columns_to_add.columns() == 0;
}

A set map holds no reference into a right block, so the right blocks can be dropped as soon as the build phase ends:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:618
void HashJoin::dropRightBlocksKeptForAnotherAlgorithm()
{
 if (!data || getMapsKind() != JoinMapsKind::Set)
 return;

and, in the build phase itself, a block that nothing references is dropped before the next one arrives:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoin.cpp:1175
 if (!block_is_referenced && last_clause)
 {
 doDebugAsserts();
 LOG_TRACE(log, "Skipping inserting block with {} rows", rows);
 data->allocated_size -= data_allocated_bytes;
 /// A set map references no block at all, so every block is dropped here even though its
 /// rows did take part in the join and must stay counted.
 if (maps_kind != JoinMapsKind::Set)
 data->rows_to_join -= rows;

For a LEFT SEMI join on a large right table, this is the difference between a join that holds the entire right side in memory and one that holds only the distinct keys.

Twenty-four variants, each its own binary

The join’s behaviour depends on two independent axes: the kind (INNER/LEFT/RIGHT/FULL) and the strictness (ALL/ANY/SEMI/ ANTI/ASOF/RIGHT ANY). That is 4 × 6 = 24 combinations, and each one generates different code: ALL needs replication, INNER needs a filter, RIGHT needs flags, ASOF needs an inequality on top of the equality.

ClickHouse compiles all of them, and does it with an explicit instantiation per variant so the compiler can optimise each separately:

 cpp
 
 
// src/Interpreters/HashJoin/LeftHashJoinAny.cpp:1
#include <Interpreters/HashJoin/HashJoinMethodsImpl.h>

namespace DB
{
template class HashJoinMethods<JoinKind::Left, JoinStrictness::Any, HashJoin::MapsOne>;
}

Six lines per variant, twenty-four files. The dispatch at run time is a static_for over the cross product, which unrolls to a switch:

 cpp
 
 
// src/Interpreters/joinDispatch.h:142
/// Call function on specified join map
template <typename MapsVariant, typename Func>
inline bool joinDispatch(JoinKind kind, JoinStrictness strictness, MapsVariant & maps, JoinMapsKind maps_kind, Func && func)
{
 return static_for<0, KINDS.size() * STRICTNESSES.size()>([&](auto ij)
 {
 // NOTE: Avoid using nested static loop as GCC and CLANG have bugs in different ways
 // See https://stackoverflow.com/questions/44386415/gcc-and-clang-disagree-about-c17-constexpr-lambda-captures
 constexpr auto i = ij / STRICTNESSES.size();
 constexpr auto j = ij % STRICTNESSES.size();
 if (kind == KINDS[i] && strictness == STRICTNESSES[j])
 {

The static_for is a compile-time loop, so the “if” is resolved at compile time for each of the 24 pairs and the runtime branch disappears entirely. What is left is a call to a template instantiation that the compiler can specialise all the way down.

The set-map dispatch is separate, because a MapsSet has a different cell layout and the code that handles a match is genuinely different — a match only marks the left row:

 cpp
 
 
// src/Interpreters/HashJoin/HashJoinMethodsImpl.h:503
/// A set map records that a key is present and nothing else: LEFT ANTI emits a row only when the key
/// is missing, and LEFT SEMI has no right-side value to emit, so a match only marks the left row.
template <
 JoinKind KIND,
 JoinStrictness STRICTNESS,
 bool need_filter,
 bool flag_per_row,
 typename MapsTemplate,
 typename Map,
 typename KeyGetter,
 typename AddedColumns>
requires SetJoinMaps<MapsTemplate>
void processMatch(

Trade-offs

What the design buys:

The joined columns are never copied into the hash table. A wide right table costs a key plus 8 bytes per distinct key in the map, not the full row.
The probe loop is a hash lookup and an append. No column copying, no type switches on the joined columns, no virtual calls per value.
The emit is a memcpy loop with a prefetch, which is close to the memory bandwidth limit and can be vectorised by the compiler.
Set maps make SEMI/ANTI joins cheap — the right table can be dropped after the build.

What it costs:

The right table stays in memory in full. There is no “the map holds the data” option, so a join whose right side does not fit in memory has to use a spilling algorithm (grace_hash) or a merge join.
The ref word is 8 bytes and the block number is 31 bits. The join is limited to 2^31 stored blocks and 2^32 rows per block; both limits are checked explicitly rather than assumed.
The 48-bit arena pointer is an assumption about the address space. It holds on Linux x86-64 and arm64 today; the code carries a diagnostic for the case where it might not.
The laziness is a two-phase affair. The probe produces words and the gather produces columns, so the result of a probe is not usable until the gather runs. That is invisible in the API but it is why the result object is a separate type (HashJoinResult) rather than a Block.
Twenty-four code paths. Every change to join semantics has to be checked against each kind × strictness combination, and the flags logic alone has three different granularities (no flags, per offset, per row).

Wrapping up

The one thing to remember: the hash table is a directory, not a store. It maps a key to an 8-byte address, and the address is resolved into columns later. If you are reasoning about the memory of a ClickHouse join, you should reason about the right table plus key + 8 bytes per distinct key, not about the joined rows.

The part people get wrong: the join does not drop the right table. A LEFT SEMI join does (it uses a set map), but an ordinary INNER ALL join holds every right-side column in memory until the query ends. When people expect a hash join to be “one copy of the right table”, they are right, and that is exactly the limit that pushes large joins to grace_hash.

What to go do about it: if a join is spilling or OOMing, look at the right side’s size, not at the number of result rows. And if the right side is small but the join is still slow, remember that the gather is where the time goes: it is a random-access gather from the stored blocks, in the order the probe decided, not in the order the right table is stored. The 32-row prefetch is there to hide exactly that.

Joins 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's Merge Join Walks Two Sorted Streams and Skips Whole Runs

The join object is a dummy

The planner sorts both sides

Before sorting: filter with a set

The cursor

The fused comparison

Equal runs

The output is an index map, not a copy

The ANY case has to remember the previous block

ASOF

Parallelism: sharding by hash

The other way to parallelise: primary-key ranges

Trade-offs

Wrapping up

ClickHouse's Hash Join Stores the Right Table as 64-bit Row Words

The word

Duplicates live in an arena node

Choosing the map

The right table itself

The “used” flags

The probe does not materialise columns

The gather kernel

Some joins need no right rows at all

Twenty-four variants, each its own binary

Trade-offs

Wrapping up

The `ANY` case has to remember the previous block