@quereus/quereus 4.16.0 → 4.17.1

package/dist/src/planner/rules/cache/rule-nested-loop-right-cache.js

@@ -103,14 +103,18 @@ function estimateRightRows(node) {
     }
     return max;
 }
-export function ruleNestedLoopRightCache(node, context) {
-    // Only logical JoinNodes reach here uncached. By PostOptimization,
-    // join-physical-selection has already converted every equi-join it wanted to
-    // hash/merge (those materialize their build side), so any surviving logical
-    // JoinNode IS a nested loop — the exact structural signal we need.
-    if (!(node instanceof JoinNode)) {
-        return null;
-    }
+/**
+ * Would this join's right side be wrapped in a `CacheNode` by
+ * {@link ruleNestedLoopRightCache}? The single source of truth for that
+ * question: the rule below calls it and then builds the node, and
+ * `rule-join-physical-selection` calls it to decide whether a plain nested loop
+ * pays its inner side's first-row latency ONCE (cached: one open plus N buffer
+ * replays) or once per outer row (uncached: N re-opens). Neither caller may
+ * restate any of the gates.
+ *
+ * Every gate is a decline; the comments on each explain what it protects.
+ */
+export function canCacheNestedLoopRight(node, context) {
     // Driver gate: only the left-driven join types re-scan the right side.
     // `right` / `full` buffer the left side once and scan the right side once
     // (`emitLoopJoin.driveFromRight`), so caching their right side is pure waste.
@@ -124,23 +128,23 @@ export function ruleNestedLoopRightCache(node, context) {
     // (same reopen count until the buffer fills, a win after), just data-dependent
     // rather than the guaranteed replay inner/cross/left get.
     if (node.joinType === 'right' || node.joinType === 'full') {
-        return null;
+        return false;
     }
     const right = node.right;
     // Already cached (e.g. by cte / in-subquery / mutating-subquery cache).
     if (CapabilityDetectors.isCached(right) && right.isCached()) {
-        return null;
+        return false;
     }
     // Purity gate: side effects are the mutating-subquery-cache rule's job.
     // Double-wrapping a write would change nothing and only burn memory.
     if (PlanNodeCharacteristics.subtreeHasSideEffects(right)) {
-        return null;
+        return false;
     }
     // Determinism gate: a non-deterministic right side (e.g. `random()`) must be
     // re-evaluated per left row to preserve today's observable behavior; caching
     // would freeze the first scan's values across every subsequent left row.
     if (!PlanNodeCharacteristics.isDeterministic(right)) {
-        return null;
+        return false;
     }
     // Correlation gate: a right subtree that references left attributes (a
     // parameterized/lateral seek produced by predicate pushdown) is
@@ -149,24 +153,59 @@ export function ruleNestedLoopRightCache(node, context) {
     // separate JoinNode.condition child, not inside the right subtree — so the
     // bare right access has no external refs and is cacheable.
     if (isCorrelatedSubquery(right)) {
-        return null;
+        return false;
     }
     // CTE-safety gate: eagerly materializing a CTE-backed right side breaks the
     // join's row-context at runtime (see subtreeTouchesCte above).
     if (subtreeTouchesCte(right)) {
-        return null;
+        return false;
     }
     // Size gate (memory safety): materializing an unbounded right side trades I/O
     // for memory. Respect the existing nested-loop caching threshold.
     const estimatedRows = estimateRightRows(right) ?? context.tuning.defaultRowEstimate;
     if (estimatedRows > context.tuning.join.maxRightRowsForCaching) {
         log('Right side too large to cache (%d rows > %d), skipping', estimatedRows, context.tuning.join.maxRightRowsForCaching);
+        return false;
+    }
+    return true;
+}
+/**
+ * Is this join's right side opened ONCE per join rather than once per outer row?
+ * True two ways: it is already materialized (a `CacheNode` from this rule on an
+ * earlier visit, or from the cte / in-subquery / mutating-subquery caches — all
+ * of which scan once and replay a buffer), or {@link canCacheNestedLoopRight}
+ * says this rule is about to make it so.
+ *
+ * `rule-join-physical-selection` asks THIS question, not the cacheability one:
+ * the two differ exactly on an already-cached right side, which
+ * `canCacheNestedLoopRight` declines (nothing left to do) but which pays its
+ * first-row latency once, not per outer row. Pricing that side per outer row
+ * made the selection rule re-visit a join this rule had just improved, re-price
+ * its nested loop as if the cache were not there, and convert it to a hash join
+ * — discarding the cache and landing on the costlier plan.
+ */
+export function nestedLoopRightOpensOnce(node, context) {
+    const right = node.right;
+    if (CapabilityDetectors.isCached(right) && right.isCached())
+        return true;
+    return canCacheNestedLoopRight(node, context);
+}
+export function ruleNestedLoopRightCache(node, context) {
+    // Only logical JoinNodes reach here uncached. By PostOptimization,
+    // join-physical-selection has already converted every equi-join it wanted to
+    // hash/merge (those materialize their build side), so any surviving logical
+    // JoinNode IS a nested loop — the exact structural signal we need.
+    if (!(node instanceof JoinNode)) {
+        return null;
+    }
+    if (!canCacheNestedLoopRight(node, context)) {
         return null;
     }
-    log('Caching pure nested-loop right side (%s, %d rows)', node.joinType, estimatedRows);
+    const right = node.right;
+    log('Caching pure nested-loop right side (%s)', node.joinType);
     // Memory strategy + a CacheNode threshold (which degrades to pass-through
     // past its limit) mirrors the sibling mutating-subquery-cache rule. Spill is
-    // unreachable under the size gate above (maxRightRowsForCaching <
+    // unreachable under `canCacheNestedLoopRight`'s size gate (maxRightRowsForCaching <
     // cache.spillThreshold), so 'memory' is the only live choice here.
     const threshold = CachingAnalysis.getCacheThreshold(right);
     const cached = new CacheNode(right.scope, right, 'memory', threshold);

package/dist/src/planner/rules/cache/rule-nested-loop-right-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-nested-loop-right-cache.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-nested-loop-right-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rule-nested-loop-right-cache.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-nested-loop-right-cache.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/rules/join/index-nested-loop.d.ts

@@ -1,49 +1,123 @@
 /**
  * Index-nested-loop candidate construction for `rule-join-physical-selection`.
  *
- * When a join's inner (right) side bottoms out in a plain every-row walk over a
- * table whose module can answer an equality seek on the join key, the walk is
- * replaced by an `IndexSeekNode` whose seek keys are column references into the
- * OUTER row. The node above stays the logical `JoinNode`, so the existing
- * nested-loop emitter drives it: for each outer row it installs the outer row
- * slot and re-opens the inner pipeline, and the seek-key expressions resolve
- * through the runtime context by attribute id — the same machinery correlated
+ * When a join's inner side bottoms out in a table-access leaf whose module can
+ * answer an equality seek on the join key, the leaf is replaced by an
+ * `IndexSeekNode` whose seek keys are column references into the OUTER row.
+ * The node above stays the logical `JoinNode`, so the existing nested-loop
+ * emitter drives it: for each outer row it installs the outer row slot and
+ * re-opens the inner pipeline, and the seek-key expressions resolve through
+ * the runtime context by attribute id — the same machinery correlated
  * subqueries already exercise.
  *
  *   Join(inner, s, SeqScan(big))          Join(inner, s, IndexSeek(big, keys=[s.k]))
  *     ON big.id = s.k              ──▶      ON big.id = s.k
  *   reads every row of big                 one seek per row of s
  *
+ * Two admission arms for the inner leaf. A WALK leaf (plain full scan, or an
+ * ordering-only index walk) enforces nothing, so its `FilterInfo` may be
+ * replaced wholesale. A SEEK leaf (`IndexSeekNode`) already enforces the
+ * predicates the module claimed — `status = 'x'` below is nowhere else in the
+ * tree — so it is admitted by re-OFFERING those predicates to the module
+ * alongside the join key and re-applying whatever the module declines:
+ *
+ *   Join(inner, s, IndexSeek(big, [status='x']))
+ *     ON big.id = s.k
+ *       ──▶  Join(inner, s, Filter[status='x'](IndexSeek(big, keys=[s.k])))
+ *       or   Join(inner, s, IndexSeek(big, keys=[status='x', s.k]))   (composite index)
+ *
+ * The function takes `outer` / `inner` explicitly rather than reading a
+ * JoinNode's `left` / `right`: the caller asks for BOTH orientations of an
+ * inner join (seek the right driven by the left, and the mirror) and elects
+ * the cheaper — see `ruleJoinPhysicalSelection`. Here "outer" always means the
+ * side that will drive, and "inner" the side whose leaf becomes the seek,
+ * whichever JoinNode slot each came from.
+ *
  * This module only CONSTRUCTS the candidate (recognize the shape, probe the
- * module, cost it); the four-way cost comparison and the join rebuild live in
- * the caller. Every gate below declines by returning null, which leaves the
+ * module, cost it); the cost comparison and the join rebuild live in the
+ * caller. Every gate below declines by returning null, which leaves the
  * nested-loop / hash / merge competition unchanged.
  *
  * NOTE: one extra pair of `getBestAccessPlan` probes runs per qualifying
- * equi-join, uncached (see `probeModule`). Cheap for both shipped modules;
- * memoize by (table, seek columns) only if a third-party module with an
- * expensive planner shows up in optimization profiles — mirrors the
- * rule-key-set-seek tripwire.
+ * equi-join on the walk arm, uncached (see `probeModule`); the seek arm runs
+ * ONE probe — its baseline is the displaced seek's recorded cost, a field read
+ * rather than a second probe. Cheap for both shipped modules; memoize by
+ * (table, offered constraints) only if a third-party module with an expensive
+ * planner shows up in optimization profiles — mirrors the rule-key-set-seek
+ * tripwire.
  */
 import type { RelationalPlanNode } from '../../nodes/plan-node.js';
 import type { OptContext } from '../../framework/context.js';
-import { JoinNode } from '../../nodes/join-node.js';
+import type { JoinType } from '../../nodes/join-node.js';
 import type { EquiJoinPair } from '../../nodes/join-utils.js';
+import { type PredicateConstraint } from '../../analysis/constraint-extractor.js';
+import type { TableSchema } from '../../../schema/table.js';
 export interface IndexNestedLoopCandidate {
-    /** Rebuilt right subtree with the access leaf replaced by the correlated seek. */
-    readonly newRight: RelationalPlanNode;
+    /**
+     * Rebuilt INNER subtree with the access leaf replaced by the correlated seek.
+     * Which JoinNode slot it belongs in is the caller's business — it is the
+     * `inner` argument's slot, which is the right one only in the un-mirrored case.
+     */
+    readonly newInner: RelationalPlanNode;
     /** Engine-currency cost, comparable with nestedLoop/hash/merge in the caller. */
     readonly cost: number;
+    /**
+     * The two inputs `cost` was derived from, so the caller can re-price the same
+     * seek under a different driver (`batchedIndexNestedLoopJoinCost`) without
+     * re-probing: the module's row estimate for one seek, and the inner
+     * subtree's first-row latency.
+     */
+    readonly rowsPerSeek: number;
+    readonly perSeekLatencyMs: number;
+    /**
+     * True when the rebuilt inner PROVABLY yields at most one row per outer row —
+     * see {@link provesAtMostOne}. What lets the caller drive this candidate as a
+     * one-branch `FanOutLookupJoinNode` (`atMostOne-*` branch), whose runtime
+     * throws on a second row.
+     */
+    readonly atMostOne: boolean;
 }
 /**
- * Try to build an index-nested-loop candidate for `node`: the right subtree
- * rebuilt with its access leaf replaced by a correlated `IndexSeekNode`, plus
+ * PROOF — not an estimate — that the inner rebuilt from `combined` yields at
+ * most one row per outer row. `FanOutLookupJoinNode`'s `atMostOne-*` branch
+ * modes throw `QuereusError(CONSTRAINT)` at runtime on a second row, so the
+ * module's `rows: 1` estimate must not stand in: a module that estimates 1 and
+ * returns 2 would turn a working query into an error.
+ *
+ * Premise: every constraint in `combined` is enforced somewhere inside the
+ * rebuilt inner. That is total for the `=` constraints this proof reads, by
+ * construction rather than by argument — each one is either module-DECLINED, and
+ * `reapplyDeclinedPushed` re-applies every declined pushed constraint as a Filter
+ * (join-key leftovers need none: the ON condition the caller keeps above the seek
+ * covers them), or module-HANDLED, and a handled constraint is either consumed
+ * into the seek's bounds or recovered by `selectPhysicalNode`'s
+ * `reattachUnconsumedConstraints` — whose `RECLAIMABLE_OPS` set contains `'='`,
+ * so no equality can fall through it. A Filter only removes rows, so a constraint
+ * enforced by a filter rather than by the index counts just the same. Then: if
+ * some enforced key has EVERY column pinned by an equality whose collation
+ * refines the key's ({@link equalityRefinesKey}), any two surviving rows agree
+ * on the whole key and uniqueness forbids the second. Ranges, IN and OR_RANGE
+ * admit many values and never contribute. Over-fetch is harmless — a
+ * `COARSER_SAFE` seek's residual Filter re-applies the exact comparison above
+ * it — and the finer-index case (`MISMATCH_UNSAFE`) never reaches here: it
+ * degrades to a scan in `selectPhysicalNode` and `rebuiltSeek` declines the
+ * candidate first. NULL keys need no case: `col = NULL` matches nothing.
+ *
+ * Exported for direct unit coverage; it is the correctness core of the batched
+ * candidate.
+ */
+export declare function provesAtMostOne(tableSchema: TableSchema, combined: readonly PredicateConstraint[]): boolean;
+/**
+ * Try to build an index-nested-loop candidate: the `inner` subtree rebuilt with
+ * its access leaf replaced by an `IndexSeekNode` correlated to `outer`, plus
  * its engine-currency cost. Returns null when any gate declines; the caller's
  * nested-loop / hash / merge competition is then unchanged.
  *
- * `equiPairs` must be non-empty and oriented left=outer / right=inner (as
- * `extractEquiPairs` produces for this join). `outerRows` is the caller's
- * left-side estimate — the same input hash and merge selection use.
+ * `joinType` is the type the REBUILT join will have with `outer` on the left
+ * (so a mirrored inner join passes 'inner'). `equiPairs` must be non-empty and
+ * oriented left=outer / right=inner — the caller flips them for the mirror.
+ * `outerRows` is the outer side's row estimate, the same input hash and merge
+ * selection use for that side.
  */
-export declare function tryIndexNestedLoop(node: JoinNode, equiPairs: readonly EquiJoinPair[], outerRows: number, context: OptContext): IndexNestedLoopCandidate | null;
+export declare function tryIndexNestedLoop(joinType: JoinType, outer: RelationalPlanNode, inner: RelationalPlanNode, equiPairs: readonly EquiJoinPair[], outerRows: number, context: OptContext): IndexNestedLoopCandidate | null;
 //# sourceMappingURL=index-nested-loop.d.ts.map

package/dist/src/planner/rules/join/index-nested-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-nested-loop.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/index-nested-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAiB9D,MAAM,WAAW,wBAAwB;IACxC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAuND;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GACjB,wBAAwB,GAAG,IAAI,CA2EjC"}
+{"version":3,"file":"index-nested-loop.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/join/index-nested-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAS9D,OAAO,EAA+C,KAAK,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAgB/H,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D,MAAM,WAAW,wBAAwB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC5B;AA0eD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GAAG,OAAO,CAa3G;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GACjB,wBAAwB,GAAG,IAAI,CA+EjC"}