perf: infer each relation's schema once per build, not once per level

[nielspardon]

Completes #207. PR #245 removed the extension-merging half; this is the schema half.

Problem

Every verb resolves its input's schema, and plans are built as nested resolve()
closures, so an N-verb chain re-walked the whole subtree beneath it at every level.
Profiling a 40-verb project chain (45 ms total) shows the cost is not only where
the issue points:

cost centre	time
the rel_anchor index in infer_plan_schema (iter_plan_rels)	30 ms
the infer_rel_schema recursion — the half #207 names	9 ms
assembling the protobuf (_plan_from)	2 ms

Indexing anchors walks every relation and every expression of the plan, to reach
the relations embedded in subqueries. Doing that per level made it the larger term,
so fixing only the recursion would have left two thirds of the cost in place.

Approach

Assigning an input's root Rel into the output relation copies it, so the schema just
inferred for that input is unreachable from the copy by identity — a plain identity
cache never hits across levels. The copy is reachable as it is made, though, and
protobuf wrappers are identity-stable, so _plan_from records that each copy carries
its input plan's output schema; infer_rel_schema consults those records before
dispatching and stops there instead of recursing through. reference and
with_execution_behavior assemble a Plan directly and record their own root; the
read builders and update are already leaves.

What is recorded is the plan, not the schema, resolved on first lookup — set,
reference and exchange never look at their input's schema, and inference can fail
where building does not, so resolving eagerly would reject plans that build today.
Only builders write to the memo: a relation's output struct can depend on ambient
correlation context (outer_schemas, anchor_scope), and anything crossing into
another context is copied on the way, so a record is only ever read back under the
context it was made in. Caching inference results wholesale would not have that
property. build_scope scopes the memo alongside the build's ExtensionCollector, so
inference used directly as a library function is untouched.

An entry keys on a live submessage, and a submessage keeps its whole plan's arena, so
entries left to accumulate would hold every intermediate plan of the build — 26 MB
against 10 MB over a 32-verb chain on a 2000-column table. Each is released once a
lookup has resolved through it, which restores flat retention with the inference counts
unchanged.

DataFrame.rename, drop and hint built their resolvers as plain closures rather
than via build_scoped, so no build scope covered them and they were the one public
path the memo could not reach. They are wrapped like every other verb.

Two supporting details: infer_plan_schema passes its anchor index as a factory that
_AnchorScope calls on the first lookup needing one, and the pairing between a record
and its relation is positional — the i-th child Rel in declaration order is the i-th
bound input, which is how every builder places them. The count is checked, and a
parametrized test over every multi-input builder pins the order, since a silent swap
would hand the level above a join its two sides' schemas the wrong way round.

Result

infer_rel_schema calls per build, and relations visited while indexing anchors:

verbs	main	this branch
5	15 / 15	16 / 0
10	55 / 55	36 / 0
20	210 / 210	76 / 0
40	820 / 820	156 / 0

N(N+1)/2 becomes 4N-4, and the anchor index is never built for a plan with no
id-based outer reference. Every shape follows: at 16 verbs, join+select goes 800 →
187, lateral_join+select 1088 → 251, group_by/agg 528 → 124, and rename —
which no build scope used to cover — 272 → 91. Peak memory stays flat in chain length,
matching main (10.2 MB against 9.9 MB at 32 verbs over a 2000-column table).

Build time, best of 7 through the DataFrame API:

shape	main @ 8 / 16 verbs	this branch @ 8 / 16
with_columns	5.2 / 14.2 ms	3.2 / 6.7 ms
filter over cache()	4.5 / 12.4 ms	2.6 / 5.1 ms
join + select	17.9 / 60.6 ms	5.9 / 13.5 ms
lateral_join + select	20.4 / 66.1 ms	6.6 / 15.0 ms
group_by / agg	9.0 / 29.0 ms	3.9 / 9.1 ms

What remains per level is the protobuf copy in _plan_from, which is proportional to
the plan's byte size and inherent to assembling nested immutable messages — so
building is still quadratic in plan bytes, with a constant roughly twenty times
smaller than the term removed here.

One behavior change

join, hash_join and merge_join derived their post_join_filter output schema by
re-inferring from the input relations, passing neither input's shared-subtree list — so a
reference()-promoted (i.e. .cache()d) input, whose root is a plan-global
ReferenceRel, could not resolve. On main all three raise ReferenceRel subtree_ordinal 0 is out of range; the memo silently answered the ReferenceRel and
masked it, which would have left the memo load-bearing for correctness on an untested
path. They now combine the schemas already inferred a line above, as lateral_join
always did, so the case builds independently of the memo — and one redundant walk of both
input subtrees per join goes away with it. tests/builders/plan/test_reference.py covers
all three; it passes with the memo disabled, which is what shows the hidden dependence is
gone.

Verification

Emitted plans are unchanged, which is the property that matters most here, so it was
checked rather than assumed: 42 plans covering every builder — including the
multi-input, cache(), lateral_join and subquery shapes — are byte-identical to a
main worktree, and every example prints output identical to it — which CI does not
check, since it runs four of them and only asserts they exit cleanly
(duckdb_example still executes its plan to the same result set).

Both new cost tests fail with the memo lookup removed (528 inferences against a bound
of 216), and all six pairing tests fail with the pairing reversed.

That comparison also turned up two pre-existing coverage gaps, closed here: nothing
inferred a SortRel's schema, since sort is always terminal in the suite and had no
direct unit test, and column() was only ever called with a name, never an ordinal.
The sort branch sits in the function the memo now short-circuits, so leaving it
uncovered would mean a change there could only be caught downstream.

Closes #207

🤖 Generated with AI