@quereus/quereus 4.16.0 → 4.17.0

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"}