[jnsdls]

Summary

Ports upstream 1.11.3's query interning to the builder. When a step repeats one taken before, the builder returns the query it built then instead of building it again.

query.where(field, op, value)
  key = (step, every argument, type-tagged)       # 1 / 1.0 / True / "1" stay apart, floats by hex
  if parent._children[key] is alive: return it    # children held weakly, parent strongly
  build the child, remember it under key
  hold it in _RECENT (last 4096 built)            # CPython frees a dropped chain at once; V8 waits for GC

Subqueries (related, exists) are keyed by the identity of their query's AST. The new CorrelatedSubquery.source field keeps that query alive. A two-hop exists builds its junction AST new every time, so it's keyed by its junction condition instead. Python's keys are exact where upstream's aren't: upstream folds a flip of 'yes' into true.

Stacked on #39, which this wins back the builder slowdown for.

Evidence

Wall-clock, Python median, same machine:

case	main (1.10.0)	#39	this PR
build.simple	3.5 µs	4.6 µs	1.3 µs
build.complex	20.8 µs	25.2 µs	13.7 µs
query.simple.b100	834 µs	907 µs	547 µs
query.complex.b100	3.69 ms	4.17 ms	2.78 ms

• test_rebuilt_queries_match_upstream: the same programs three times in one batch through one builder, compared with the npm package. They cover every step kind: scalar and float where, whereFn with a static parameter and exists, two-hop whereExists, a raw condition, related with and without a callback, orderBy, nested start, limit and one.
  • Before the two-hop key fix (0d4781b): fails. scalar: true then false returned the first query.
  • After: passes.
• uv run pytest: 784 passed, 100% coverage. uv run python -m tests.compat: fully exercised.

Merge Danger

Door: two-way

Blast Radius: builder

Queries built from the same builder now share objects. Their ASTs equal what fresh building gives, including when a caller later mutates a list it passed in, which upstream does the same way. Memory is bounded: children are held weakly, plus at most 4096 recently built queries.

Reviewed with sol-loop: 2 rounds with gpt-6.1-sol. Sol verdict: approved

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[codspeed]

Merging this PR will improve performance by 8.66%

1 warning, 1 note

⚠️ Base and head ran on different runner types

Some benchmarks with significant performance changes were compared across different runner types, so the changes might not come from the code. Run base and head on the same runner type, or use CodSpeed Macro Runners for more stable results.

Learn more about Macro Runners

Open the report in CodSpeed to investigate

ℹ️ 3 benchmarks have no flamegraph

The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.

See affected benchmarks

⚡ 13 improved benchmarks
❌ 8 (👁 8) regressed benchmarks
✅ 25 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_cpu[build.simple]	175.2 µs	94.3 µs	+85.91%
⚡	build.simple	131.3 µs	77.6 µs	+69.22%
⚡	map.complex	265.9 µs	159.6 µs	+66.58%
⚡	map.simple	107.9 µs	69.6 µs	+55.01%
⚡	test_cpu[query.simple.b100]	22.1 ms	15.2 ms	+45.5%
⚡	build.complex	454 µs	341.8 µs	+32.82%
⚡	test_cpu[query_json.simple.b100]	32.3 ms	25.9 ms	+25.04%
⚡	test_cpu[build.complex]	678.4 µs	555.5 µs	+22.12%
⚡	test_cpu[query.complex.b100]	87.8 ms	72.5 ms	+21.13%
⚡	test_cpu[query.simple.b1]	486.7 µs	407.6 µs	+19.41%
⚡	test_cpu[query.complex.b1]	1.2 ms	1 ms	+13.61%
⚡	test_cpu[query_json.simple.b1]	696.8 µs	613.7 µs	+13.54%
⚡	test_cpu[query_json.complex.b100]	141.5 ms	127.8 ms	+10.69%
👁	test_cpu[parse_json.transform.q1000]	56.8 ms	67.4 ms	-15.72%
👁	parse.push.m1000	45.4 ms	51.4 ms	-11.65%
👁	query_json.complex.b100	61.4 ms	85.3 ms	-27.95%
👁	query_json.simple.b1	747.3 µs	872.1 µs	-14.31%
👁	query_json.simple.b100	14 ms	19.5 ms	-28%
👁	query.complex.b1	1.1 ms	1.3 ms	-11.2%
👁	query.complex.b100	42.9 ms	70.2 ms	-38.95%
...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing perf/intern-queries (6883126) with main (a6ad73e)}