[Hor911]

Summary

The join-order estimator divides a pair's rows by the larger of its two key domains. Where a domain was unknown
it stood in the relation's row count, "which is the most distinct values it could have" — true, and the wrong
direction. The two helpers sat beside each other with the same word and opposite safety:

// A relation's rows: unknown counts as the largest, since unknown must never read as small
int64_t BlockRows(...)

// A key's distinct values: the footers' domain where there is one, else its relation's rows,
// which is the most distinct values it could have.
int64_t BlockDomain(...)

Rows multiply, so the largest reading is the most rows — safe. A domain divides, so the largest reading
is the fewest rows, which is the one direction an estimate may not err in: under-stating a build's rows is what
materialises a side that does not fit (ADR 0026's C5), and under-stating an intermediate is what lets the search
pick a plan that multiplies.

A derived table's columns carry no domain at all, because the binder reads one only from a table
(binder.cc:4639-4643). So an edge between a base-table column of 25 values and a derived column of
1,200,243 rows divided by 1,200,243 instead of by 25. A join the search ranked cheapest at 150,000 rows
produced 6,697,748,923 of them.

An edge now divides by the largest of the domains the footers know, with an unknown side contributing nothing.
One known side is enough. Where neither is known the edge divides by 1 and the join reads as the product of its
inputs — deliberately the most pessimistic reading available, since any value between "the largest domain
possible" and "no information" is a guess, and a guess here is paid for in materialised rows.

Closes #

Type of change

• feat: new SQL, CLI or engine capability
• fix: bug fix
• perf: performance improvement
• refactor, test, docs, build, ci or chore
• Breaking change (CLI, output format or semantics); also add the breaking-change label

Verification

$ pixi run ci                 # clang Debug -Werror + the hermetic suite
100% tests passed out of 2813

$ pixi run release
100% tests passed out of 2814

$ ANTB1_DIFF_SEED=20261023 pixi run diff-random
DIFF: PASS seed=20261023 queries=2000 failed=0 unsupported=0

$ pixi run lint
every hook Passed except shellcheck: 37 pre-existing SC2218 findings in scripts/ and tools/github/, on files
this PR does not touch. `git stash && pixi run lint` fails identically on main and CI's lint leg passes, so this
host's shellcheck is the stricter one. `pixi run check` therefore cannot complete locally; `pixi run ci` was run
directly.

$ clang-tidy -p build/tidy --warnings-as-errors='*' src/plan/join_order.cc
clean

$ ASAN_OPTIONS=detect_leaks=0 ./build/ci-asan/bin/antb1_plan_tests
814 tests PASSED
`pixi run asan` cannot run on this host (it fails at discovery on a pre-existing curl_global_init leak), so the
binary was run directly after generating the ci-asan fixtures.

Not run on this host: pixi run ci-gcc and codeql-build (the gcc environment is linux-64 only).

Performance. SF 100, four threads, both arms built from this branch and main. TPC-H-derived data generated
locally; not TPC-H Benchmark results.

	before	after
a query reaching the shape	145.2 s	140.6 ms (1033x)
its largest intermediate	6,697,748,923	168,231
Q09 — the query ADR 0026's C5 rule protects	14.103 s	14.220 s, identical answer
the 22		1.002x geomean, peak unchanged

The 22 do not move because none of them reaches the shape: no unmodified query joins on a derived table's
column inside a block where the order matters. Every rewrite that introduces a derived table does reach it, which
is how this was found — the first attempt at moving a grouped aggregate below a join hit it immediately. With the
domain read correctly the estimate lands within 8% of the truth, so it is one wrong input and nothing else.

Checklist

• pixi run check passes locally (lint + clang Debug -Werror + hermetic tests) — not ticked: see the
  shellcheck note. Both halves were run separately and pass.
• Tests cover the change (unit tests under src/<module>/tests/, or why none are needed)
• Docs updated where behavior, commands or architecture changed (AGENTS.md, docs/, an ADR), or not needed
• No ClickBench-derived data is committed: no Parquet files, query answers or values from hits (ADR-0006)
• Nothing derived from TPC-H is committed: no query text or fragments, data, answers or TPC tools (ADR-0006)
• Changes to governance paths (see .github/CODEOWNERS) were agreed with a maintainer

The one open checklist item: this amends docs/adr/0022-joins-and-query-blocks.md, which CODEOWNERS covers.
It is an update to an Accepted ADR, not a status change, and it exists because that ADR stated both halves of
this hazard and never joined them up: four lines above the refinement that introduced the substitution, it says
the domains are what keep a many-to-many edge out of the order, since "ordering by row counts alone can take such
an edge first and multiply the intermediate result". The code and tests stand alone if you would rather the ADR
hunk went separately.

Tests — two corrected, not relaxed

I want to be explicit about this, because changing a test's expectation normally means weakening it. Both of
these asserted the old reading as correct:

1. JoinOrderTest.AManyToManyEdgeWaitsWhileAKeyEdgeIsAvailable asserted an estimate of 10 for a join whose
   output its own comment puts at 5,000 — a 500x under-statement, labelled "the control". It now reads
   10,000, a 2x over-statement, on the safe side.
2. BinderTest.ASemiJoinOverOneRelationRunsOnItsBranch guards against moving a semi join onto more rows than it
   would see above (ADR 0029's D0). Its comment credited "a wide key domain" that did not exist: the fixture
   registered a row count and no statistics, so the only domain in play was the substituted row count — the
   guard rested on the very substitution it was meant to test against. Rather than change the expectation, the
   fixture now declares that domain, and the number is the one the estimator used to invent, so the case reads
   as it always did and now for a stated reason.

New coverage: one known domain divides alone whichever side it is on, both-unknown reads as the product, and a
key with no value empties the join even when its partner's domain is unknown. Four mutations checked, all
caught — including one that is behaviour-identical on the divisor and differs only in losing that last case,
which is what prompted it.

A guard against the shape was considered and refused

Penalising a join whose only edge has a tiny domain fires on 9 of the 22, every one a dimension lookup where
the small side's key is its primary key — including Q09's own supplier-to-nation join, the query ADR 0026's C5
rule exists to protect. The discriminating condition is non-uniqueness on both sides, which the metadata gives
for a base table and cannot give for a derived one. So the fix belongs at the input, not at the decision.
Propagating a base column's domain through a derived table's pass-through columns would narrow the remaining gap
and is left as its own item.

AI assistance

• No AI assistance
• AI-assisted. Tools and what they did: Claude Code (Opus 5) wrote the fix, the tests and the ADR amendment,
  and ran the gates and SF 100 measurements. A subagent diagnosed it after I handed it the wrong premise — I had
  reported the 1033x as a composite-key split made unavoidable by a rewrite; it showed two of the three join
  orders avoid the bad edge entirely, which makes it an estimator failure rather than a bad graph, and traced the
  cause to the three lines above. I verified each of those myself before writing any code, including re-running
  the 1033x and confirming the fixture declares no statistics.
• Accountable human (has read and understands the whole diff): @Hor911

[claude]

Claude finished @Hor911's task in 20s —— View job

---

Claude review: no problems found

I read the full diff against the AGENTS.md review rules. That covers src/plan/join_order.cc, the three test files and the ADR 0022 amendment. I did not build or run the tests.

• join_order.cc: the old BlockDomain is replaced by DivisorOf. An unknown domain now contributes nothing, and a known domain of 0 still empties the join. Both JoinRowsOf and DivisorsOf use it, and the relations parameters that became unused are gone. I found no case where the change makes results wrong. If an input has 0 rows, the join is still empty through left == 0 || right == 0, which replaces the old fallback to the row count.

• Tests: the new cases cover:

  • a single known domain, on either side;
  • neither side known, which reads as the product of the inputs;
  • a known zero domain next to an unknown one.

  The two corrected expectations come with a stated reason in the diff. I can't judge here whether they weaken anything, because I didn't run them.

P2 notes

• The doc comment in join_order.cc says "1013x", but the PR body and the ADR say 1033x.
• The ADR amendment is dated 2026-10-22, which is after today's date (2026-10-21).

"Ask a human first" paths changed: none from the AGENTS.md list. docs/adr/0022-joins-and-query-blocks.md is covered by CODEOWNERS, and the PR body already says the maintainer has not yet agreed to it. The amendment doesn't change the ADR's status.

Not reviewed: I did not run pixi run check, ASan, tidy or the GCC leg, and I did not check the performance numbers. They come from the PR description.

[github-actions]

Coverage

Module	Lines	Floor	Branches	Floor	Status
common	98.07% (203/207)	92.9%	92.44% (110/119)	90.8%	ok
sql	99.08% (3244/3274)	97.3%	97.64% (2190/2243)	95.6%	ok
plan	95.60% (8821/9227)	93.5%	90.09% (4726/5246)	89.5%	ok
io	94.30% (1241/1316)	93.2%	90.49% (723/799)	86.6%	ok
exec	97.05% (11191/11531)	96.1%	88.48% (6300/7120)	85.1%	ok
engine	95.98% (478/498)	93.0%	88.52% (239/270)	85.1%	ok
cli	94.59% (647/684)	93.4%	87.08% (283/325)	86.4%	ok
total	96.59% (25825/26737)		90.38% (14571/16122)

Coverage gate: PASS (floors: tools/ci/coverage_thresholds.json; they only go up).

Clang source-based coverage of the hermetic tests over src/<module>/ (module unit tests excluded); N/A: nothing to cover. Reproduce with pixi run coverage (details: build/coverage/report.txt).