@quereus/quereus 3.1.1 → 3.2.1

package/dist/src/planner/rules/parallel/rule-async-gather-union-all.js

@@ -0,0 +1,115 @@
+/**
+ * Rule: Async Gather UNION ALL
+ *
+ * Recognizes a chain of `SetOperationNode(op='unionAll')` and folds the entire
+ * left-deep (or arbitrary nesting) tree into a single N-ary
+ * `AsyncGatherNode({ kind: 'unionAll' })` that drives the N branches
+ * concurrently.
+ *
+ * Two gates must clear for the rewrite to fire:
+ *
+ *   1. **Concurrency safety.** Every flattened child must declare
+ *      `physical.concurrencySafe === true`. Any non-safe branch (mutating
+ *      subplan, serial-module read without a per-branch connection, holding a
+ *      non-reentrant cursor) poisons the rewrite — leave the chain as
+ *      sequential `SetOperationNode`s.
+ *
+ *   2. **Latency win.** The slowest child's `physical.expectedLatencyMs` must
+ *      meet `tuning.parallel.gatherThresholdMs`. `expectedLatencyMs` is 0 on
+ *      all in-process / memory-vtab paths, so the rule is inert by design in
+ *      local-only configurations (the no-rewrite invariant is locked by the
+ *      golden-plan sweep).
+ *
+ * The rule fires in `PassId.PostOptimization` after physical-property
+ * selection has finalized `expectedLatencyMs` / `concurrencySafe` on the
+ * leaves but before `materialization-advisory` so any cache wrapping the
+ * advisory would inject sits *inside* the gather's branches (preserving the
+ * parallel-drive intent of overlapping high-latency I/O with branch-local
+ * compute).
+ *
+ * Attribute IDs are preserved: the rewritten gather node inherits the
+ * outermost `SetOperationNode`'s attributes via `preserveAttributeIds`,
+ * which already mirrors the leftmost child's attributes per
+ * `SetOperationNode.buildAttributes`. Downstream consumers that referenced
+ * the SetOp's output (e.g. an enclosing `ORDER BY x`) continue to resolve
+ * unchanged.
+ *
+ * Idempotence: after the rewrite the root node is an `AsyncGatherNode`, not
+ * a `SetOperationNode`, so a second firing's matcher rejects immediately.
+ */
+import { createLogger } from '../../../common/logger.js';
+import { PlanNodeType } from '../../nodes/plan-node-type.js';
+import { SetOperationNode } from '../../nodes/set-operation-node.js';
+import { AsyncGatherNode } from '../../nodes/async-gather-node.js';
+const log = createLogger('optimizer:rule:async-gather-union-all');
+export function ruleAsyncGatherUnionAll(node, context) {
+    if (!(node instanceof SetOperationNode))
+        return null;
+    if (node.op !== 'unionAll')
+        return null;
+    const tuning = context.tuning.parallel;
+    if (tuning.minBranches < 2)
+        return null;
+    // Flatten the entire unionAll tree (any shape — left-deep, right-deep,
+    // balanced). Stops at the first non-unionAll-SetOperation child.
+    const children = [];
+    collectUnionAllChildren(node, children);
+    if (children.length < tuning.minBranches)
+        return null;
+    // Gate 1: every child must be concurrency-safe. A single unsafe branch
+    // poisons the rewrite.
+    for (const child of children) {
+        if (child.physical.concurrencySafe !== true) {
+            log('Aborting rewrite: child %s is not concurrencySafe', child.id);
+            return null;
+        }
+    }
+    // Gate 2: max-of-children latency must meet the threshold. Memory-vtab /
+    // in-process leaves declare expectedLatencyMs=0, so this skips the
+    // rewrite for purely local plans (the no-rewrite invariant under the
+    // golden-plan sweep).
+    let maxLatency = 0;
+    for (const child of children) {
+        const l = child.physical.expectedLatencyMs ?? 0;
+        if (l > maxLatency)
+            maxLatency = l;
+    }
+    if (maxLatency < tuning.gatherThresholdMs)
+        return null;
+    const concurrencyCap = Math.max(1, Math.min(tuning.concurrency, children.length));
+    log('Folding unionAll chain of %d branches into AsyncGather (cap=%d, maxLatency=%d ms, threshold=%d ms)', children.length, concurrencyCap, maxLatency, tuning.gatherThresholdMs);
+    return new AsyncGatherNode(node.scope, children, { kind: 'unionAll' }, concurrencyCap, node.getAttributes());
+}
+/**
+ * Walk an arbitrary tree of unionAll-`SetOperationNode`s and push the leaves
+ * (first non-unionAll-SetOp descendant on each branch) into `out`. Recursion is
+ * bounded by the unionAll chain depth, which is the same depth bound the
+ * optimizer's pass already enforces.
+ *
+ * Also absorbs nested `AsyncGatherNode({ kind: 'unionAll' })` children — the
+ * rule is registered for bottom-up traversal, so the inner `SetOperation` of
+ * `(A unionAll B) unionAll C` will already have been rewritten into a
+ * 2-branch gather by the time the outer `SetOperation` fires. Without this
+ * absorption the outer rewrite would produce a 2-branch gather whose first
+ * child is itself a gather, defeating the "single gather per chain"
+ * invariant the tests pin.
+ */
+function collectUnionAllChildren(node, out) {
+    if (node.nodeType === PlanNodeType.SetOperation && node.op === 'unionAll') {
+        const setOp = node;
+        collectUnionAllChildren(setOp.left, out);
+        collectUnionAllChildren(setOp.right, out);
+        return;
+    }
+    if (node.nodeType === PlanNodeType.AsyncGather) {
+        const gather = node;
+        if (gather.combinator.kind === 'unionAll') {
+            for (const child of gather.children) {
+                collectUnionAllChildren(child, out);
+            }
+            return;
+        }
+    }
+    out.push(node);
+}
+//# sourceMappingURL=rule-async-gather-union-all.js.map

package/dist/src/planner/rules/parallel/rule-async-gather-union-all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-async-gather-union-all.js","sourceRoot":"","sources":["../../../../../src/planner/rules/parallel/rule-async-gather-union-all.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,MAAM,GAAG,GAAG,YAAY,CAAC,uCAAuC,CAAC,CAAC;AAElE,MAAM,UAAU,uBAAuB,CAAC,IAAc,EAAE,OAAmB;IAC1E,IAAI,CAAC,CAAC,IAAI,YAAY,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,IAAI,CAAC,EAAE,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAExC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;IACvC,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,uEAAuE;IACvE,iEAAiE;IACjE,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,uBAAuB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,IAAI,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAEtD,uEAAuE;IACvE,uBAAuB;IACvB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;YAC7C,GAAG,CAAC,mDAAmD,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;YACnE,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,yEAAyE;IACzE,mEAAmE;IACnE,qEAAqE;IACrE,sBAAsB;IACtB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,iBAAiB,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,UAAU;YAAE,UAAU,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,UAAU,GAAG,MAAM,CAAC,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAElF,GAAG,CACF,oGAAoG,EACpG,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,iBAAiB,CACrE,CAAC;IAEF,OAAO,IAAI,eAAe,CACzB,IAAI,CAAC,KAAK,EACV,QAAQ,EACR,EAAE,IAAI,EAAE,UAAU,EAAE,EACpB,cAAc,EACd,IAAI,CAAC,aAAa,EAAE,CACpB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,uBAAuB,CAAC,IAAwB,EAAE,GAAyB;IACnF,IAAI,IAAI,CAAC,QAAQ,KAAK,YAAY,CAAC,YAAY,IAAK,IAAyB,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;QACjG,MAAM,KAAK,GAAG,IAAwB,CAAC;QACvC,uBAAuB,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,uBAAuB,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1C,OAAO;IACR,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,YAAY,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,IAAuB,CAAC;QACvC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC3C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrC,uBAAuB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACrC,CAAC;YACD,OAAO;QACR,CAAC;IACF,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/src/planner/rules/parallel/rule-async-gather-zip-by-key.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Rule: Async Gather ZIP BY KEY
+ *
+ * Recognizes a `Project` over a chain of binary full-outer `JoinNode`s that
+ * all equate the **same** key column set across every participating relation,
+ * and folds the whole shape into a single N-ary
+ * `AsyncGatherNode({ kind: 'zipByKey', branchKeyAttrs, outputKeyAttrs })`.
+ *
+ * Generalizes `rule-async-gather-union-all` from the `unionAll` combinator to
+ * `zipByKey`. The recognized SQL is the natural spelling of an N-way
+ * full-outer merge on a shared key:
+ *
+ *   select coalesce(a.k, b.k, c.k) as k, a.av, b.bv, c.cv
+ *     from a full outer join b on a.k = b.k
+ *            full outer join c on a.k = c.k
+ *
+ * which the builder produces as:
+ *
+ *   Project[ coalesce(a.k,b.k,c.k) as k, a.av, b.bv, c.cv ]
+ *     Join(full, on a.k = c.k)
+ *       Join(full, on a.k = b.k)
+ *         <a>  <b>
+ *       <c>
+ *
+ * The binary full-outer chain is O(N²) null-padding and infers worse FDs than
+ * the symmetric N-ary merge; the `zipByKey` gather drives the N branches
+ * concurrently and hash-merges them by key. (Binary FULL JOIN has no runtime
+ * lowering at all — this rewrite is the only execution path for it.)
+ *
+ * ## Recognized shape
+ *
+ *   1. A `ProjectNode` whose `source` is a `JoinNode(joinType='full')`.
+ *   2. The full-join chain flattens (any nesting) into ≥ `minBranches` leaf
+ *      branches. Each join's `ON` condition is a pure conjunction of
+ *      column-ref equalities (no residual / non-equi predicate — those block).
+ *      (`USING`/`NATURAL` full joins carry no synthesized `ON` condition, so the
+ *      chain walk declines them — out of scope; see *Out of scope* below.)
+ *   3. Those equalities partition the branches' key columns into K equivalence
+ *      classes ("key positions"), and **every branch contributes exactly one
+ *      column to every class** (the shared-key precondition). A branch missing
+ *      from any class would be a cross-product, not a zip — block.
+ *   4. The projection list must express, in **any order**:
+ *        - K merged keys, each a `coalesce(...)` whose argument set is exactly
+ *          one key class's per-branch key attrs; and
+ *        - the forwarded non-key column references it selects (a subset is fine),
+ *      plus arbitrary additional pure scalar expressions over those outputs
+ *      (e.g. `coalesce(a.k, b.k) * 10`). The only hard constraint: a branch *key*
+ *      column may appear **only** inside a recognizing full-group `coalesce` — a
+ *      bare/partial reference to it (e.g. `select a.k …`) blocks, because the
+ *      per-branch key is consumed into the single merged key and is unavailable
+ *      above the gather.
+ *
+ *   When the projection happens to be exactly the emitter's canonical order
+ *   (`[K coalesce calls][branch0 non-key][branch1 non-key]…`), the gather
+ *   replaces the `Project` outright (fast path). Otherwise the gather is built
+ *   in canonical layout and wrapped in a thin reordering `Project` that
+ *   reproduces the user's list (rewriting each full-group `coalesce` to a
+ *   reference to the gather's merged-key output).
+ *
+ * ## Gates (mirror `rule-async-gather-union-all`)
+ *
+ *   - **Concurrency safety.** Every branch must declare
+ *     `physical.concurrencySafe === true`.
+ *   - **Uncorrelated branches.** No branch may reference attributes outside its
+ *     own subtree (lateral dependency) — the parallel driver forks independent
+ *     contexts. `isCorrelatedSubquery` on each branch must be false.
+ *   - **Latency win.** The slowest branch's `physical.expectedLatencyMs` must
+ *     meet `tuning.parallel.gatherThresholdMs`. This is 0 on memory-vtab /
+ *     in-process leaves, so the rule is inert by design on local-only plans
+ *     (the golden-plan no-rewrite invariant).
+ *   - **Key collation agreement.** Every key column at a given key position must
+ *     declare the *same* collation across all branches (binary or not). The
+ *     runtime comparator derives from branch 0 only, so a disagreement would
+ *     compare keys under the wrong collation. Non-binary collations are allowed:
+ *     the emitter composes the merged key deterministically from the
+ *     lowest-indexed present branch (`composeMergedKeyCells`), matching
+ *     `coalesce`'s left-to-right pick even when collation-equal keys are
+ *     byte-distinct (e.g. NOCASE merging `'A'`/`'a'`). This mirrors the
+ *     *agreement* invariant `AsyncGatherNode.validateZipByKey` enforces (which
+ *     throws on a true mismatch); checking it here declines gracefully instead.
+ *
+ * ## Attribute provenance (Option A — per-branch refs + minted output keys)
+ *
+ *   - `branchKeyAttrs[b]` — branch b's K key attr ids, in key order (distinct
+ *     per branch; each branch originates its own key id — provenance-clean).
+ *   - `outputKeyAttrs` — the K ids the `Project` minted for its `coalesce`
+ *     outputs (computed expressions → fresh ids, disjoint from all child ids).
+ *     The gather *mints* these, so `preserveAttributeIds[0..K-1] ===
+ *     outputKeyAttrs` and downstream references to the coalesced key resolve.
+ *   - `preserveAttributeIds` — the `Project`'s full output attribute list,
+ *     which (because we matched the canonical order) is exactly
+ *     `[minted keys] ++ [each branch's non-key attrs]`.
+ *
+ * ## Idempotence
+ *
+ * After the rewrite the matched node is an `AsyncGatherNode`, not a
+ * `ProjectNode`, so a second firing's matcher rejects immediately.
+ */
+import type { OptContext } from '../../framework/context.js';
+import { PlanNode } from '../../nodes/plan-node.js';
+export declare function ruleAsyncGatherZipByKey(node: PlanNode, context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-async-gather-zip-by-key.d.ts.map

package/dist/src/planner/rules/parallel/rule-async-gather-zip-by-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-async-gather-zip-by-key.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/parallel/rule-async-gather-zip-by-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAoB,MAAM,0BAA0B,CAAC;AAqBtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAmH5F"}