@quereus/quereus 4.3.1 → 4.4.0

package/dist/src/planner/rules/subquery/rule-scalar-agg-decorrelation.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Rule: Scalar-Aggregate Subquery Decorrelation
+ *
+ * Rewrites a correlated scalar-aggregate subquery in a SELECT projection into a
+ * grouped LEFT JOIN, so the inner table is scanned/aggregated ONCE instead of
+ * once per outer row:
+ *
+ *   Project[..., ScalarSubquery(Agg(Filter(corr ∧ rest, inner))) ...](outer)
+ * becomes
+ *   Project[..., <guarded value read> ...]
+ *     LeftJoin[corr]                       -- outer.a = inner.k, verbatim
+ *       outer
+ *       Aggregate(groupBy=[inner.k...], aggregates=[orig agg])
+ *         Filter(rest, inner)              -- residual inner-only predicates
+ *
+ * In SQL terms: `(select agg(x) from c where c.fk = o.k)` →
+ * `left join (select fk, agg(x) as val from c group by fk) g on g.fk = o.k`.
+ *
+ * The grouped aggregate PRESERVES the inner correlation attribute ids as its
+ * group-by output attribute ids (the same id-preservation ProjectNode applies
+ * to bare column-reference projections), so the original correlation conjuncts
+ * serve verbatim as the join condition and hash-join equi-pair extraction sees
+ * plain `colref = colref` pairs.
+ *
+ * Empty-group semantics ("the count bug"): a scalar aggregate over zero rows
+ * still yields one row (`count(*)` → 0, `sum(x)` → NULL), but the grouped join
+ * produces NO group for an outer row with no matches. The aggregate's
+ * empty-input value is computed at plan time via the exact runtime path
+ * (`finalizeFunction(cloneInitialValue(initialValue))`):
+ *   - empty value NULL (sum/min/max/avg/json_group_array/…): the join miss
+ *     already yields NULL — the replacement is a bare column reference;
+ *   - otherwise (count/total): the replacement is
+ *     `CASE WHEN <group key> IS NULL THEN <empty literal> ELSE <value> END`.
+ *     A matched row always has a non-NULL group key (the equality matched), and
+ *     an inner group with a NULL key can never match any outer row, so
+ *     `key IS NULL` holds exactly on join misses — a separate `1 AS __present`
+ *     marker column is unnecessary. This is a marker, not `coalesce(...)`, so
+ *     an aggregate legitimately returning NULL on non-empty input stays NULL.
+ *
+ * Outer references OUTSIDE the correlation conjuncts (e.g. in aggregate
+ * arguments: `json_object('entryId', e.id, …)`) are remapped to the inner
+ * column they are equated with — justified by the equality predicate — but only
+ * when the equality is value-faithful (value-discriminating collation AND same
+ * logical type); otherwise the rule bails and the subquery stays correlated.
+ *
+ * Bail (leave the subquery correlated) when:
+ *   - the subquery is uncorrelated, or correlates beyond the immediate outer;
+ *   - the inner subtree carries a side effect (per-row firing is observable);
+ *   - the subquery root is not a bare zero-group single-aggregate beneath
+ *     bare pass-through Project/Alias wrappers (a Sort/LimitOffset wrapper, a
+ *     GROUP BY, a composite expression over aggregates, or a non-aggregate
+ *     `... limit 1` shape all keep today's behavior, including the >1-row
+ *     scalar-subquery runtime error);
+ *   - the aggregate's source is not a Filter whose predicate splits into
+ *     `outer.col = inner.col` equi-conjuncts plus inner-only residuals
+ *     (non-equi correlation such as `inner.ts < outer.ts` bails);
+ *   - the aggregate's empty-input value cannot be folded to a plan-time
+ *     literal (finalize throws, is async, non-deterministic, or yields a
+ *     non-primitive);
+ *   - an outer reference outside the conjuncts is not value-faithfully
+ *     remappable.
+ *
+ * Registered unconditionally (no cost gate) after `fanout-lookup-join`, so the
+ * remote-latency fan-out path keeps first claim on the branches it is tuned
+ * for; the tiny-outer/huge-inner cost tradeoff is tracked in
+ * `backlog/feat-decorrelation-cost-model`.
+ *
+ * FOUR MATCH SITES share the identical per-subquery rewrite (`decorrelateOne`):
+ *   - `ruleScalarAggDecorrelation` — subqueries in a ProjectNode's projection
+ *     expressions; the join stack lands between the Project and its source.
+ *   - `ruleScalarAggDecorrelationAggregate` — subqueries inside an
+ *     AggregateNode's aggregate-argument (and group-by) expressions; the join
+ *     stack lands BELOW the aggregate, between it and its source. Cardinality
+ *     safety: the grouped subtree's GROUP BY keys are a unique key on its
+ *     output, so the LEFT join matches at most one row per source row — the
+ *     aggregate's input row count and multiplicity are preserved exactly, and
+ *     every existing group-by/aggregate reference resolves unchanged by
+ *     attribute id (left-side attributes stay visible through the join).
+ *   - `ruleScalarAggDecorrelationFilter` — subqueries anywhere in a FilterNode's
+ *     predicate (WHERE, and HAVING — a HAVING clause plans as a FilterNode whose
+ *     source is an AggregateNode); the join stack lands between the Filter and
+ *     its source, and the subquery reference in the predicate is substituted with
+ *     the guarded value read. A FilterNode publishes its source's attributes
+ *     verbatim, so the LEFT join's appended grouped-aggregate columns would leak
+ *     to whatever consumes the filter — and a HAVING filter is frequently the
+ *     query's output node itself (the SELECT projection is fused into the
+ *     Aggregate below it, leaving no capping Project). The rule therefore caps its
+ *     own result with a bare pass-through Project that re-exposes exactly the
+ *     Filter's original attributes; the outer columns keep their original indices
+ *     (the LEFT join places the outer on the left), so that projection's column
+ *     references — and everything above — resolve unchanged.
+ *   - `ruleScalarAggDecorrelationSort` — subqueries in a SortNode's sort-key
+ *     expressions (`order by (select count(*) from c where c.fk = o.k)`); the
+ *     join stack lands BELOW the Sort so the sort key can read the grouped
+ *     value column. A SortNode publishes its source's attributes VERBATIM (it
+ *     never consumes/hides columns the way a Project does), so the LEFT join's
+ *     appended grouped-aggregate columns would otherwise leak upward and change
+ *     the row shape every ancestor (a capping Project, a view body, a compound
+ *     arm, LIMIT/OFFSET) sees. Like the Filter site, the rule caps its result
+ *     with the same bare pass-through Project (`capToAttributes`) that
+ *     re-exposes exactly the Sort's original attributes; the outer columns keep
+ *     their original indices (the LEFT join places the outer on the left), so
+ *     that projection — and everything above — resolves unchanged.
+ *
+ *     SCOPE: like every site, `decorrelateOne` requires the correlation columns
+ *     to be attributes of the Sort's OWN source. That holds for identity
+ *     projections (`select o.* … order by (select … where c.fk = o.k)`) and
+ *     for any query that also selects the correlation column. When the SELECT
+ *     list projects the correlation column AWAY (`select o.id from o order by
+ *     (select … where c.fk = o.k)`), the Sort sits above a stripping Project
+ *     whose output no longer carries `o.k`, so the rule BAILS and the subquery
+ *     stays correlated — still correct, because the runtime resolves `o.k` from
+ *     the still-live base-scan row context below the Project; it is merely not
+ *     decorrelated. Threading the grouped value column up through a stripping
+ *     Project is tracked in
+ *     `backlog/feat-decorrelate-order-by-subquery-nonselected-column`.
+ *
+ * NESTED subqueries converge level by level: the Structural pass is top-down
+ * with rules firing BEFORE descent, so the grouped aggregate built by one
+ * level's rewrite (whose aggregate argument carries the next level's subquery,
+ * outer references already remapped to the enclosing inner columns) is itself
+ * visited later in the same pass, where the Aggregate-site rule fires on it.
+ */
+import type { PlanNode } from '../../nodes/plan-node.js';
+import type { OptContext } from '../../framework/context.js';
+export declare function ruleScalarAggDecorrelation(node: PlanNode, _context: OptContext): PlanNode | null;
+/**
+ * Aggregate-argument match site: the same rewrite for subqueries embedded in
+ * an AggregateNode's aggregate-argument (or group-by) expressions — the shape
+ * a nested aggregate subquery takes after the Project-site rewrite of its
+ * enclosing level (the enclosing rewrite's outer-reference remap makes a
+ * two-level correlation local to the new grouped aggregate's source). The join
+ * stack lands below the aggregate; see the module header for cardinality
+ * safety and multi-level convergence.
+ *
+ * NOTE: this site can also fire on an aggregate INSIDE a still-correlated
+ * subquery (e.g. when the enclosing level's remap bailed but the nested
+ * correlation is local). That is correct but the grouped subtree then
+ * re-executes per outer row — whether it beats the per-inner-row correlated
+ * plan is data-dependent; if a workload regresses here, gate this site on the
+ * enclosing subtree being decorrelated (part of
+ * `backlog/feat-decorrelation-cost-model`).
+ */
+export declare function ruleScalarAggDecorrelationAggregate(node: PlanNode, _context: OptContext): PlanNode | null;
+/**
+ * Filter match site (WHERE and HAVING): the same rewrite for a correlated
+ * scalar-aggregate subquery used anywhere in a FilterNode's predicate —
+ * `where o.total > (select avg(c.amount) from c where c.fk = o.k)`. The join
+ * stack lands between the Filter and its source, and the subquery reference in
+ * the predicate is substituted with the guarded value read; the result is
+ * `Filter[pred'](LeftJoin(outer, groupedAgg))`.
+ *
+ * HAVING needs no special-casing: `... group by o.k having sum(o.v) > (select …)`
+ * plans as a FilterNode whose source is an AggregateNode, so the aggregate's
+ * group-key / aggregate-result attributes are exactly the outer attributes the
+ * subquery correlates to — `decorrelateAll` treats the AggregateNode as the outer
+ * like any other relation.
+ *
+ * The LEFT join is load-bearing (an outer row with no inner match survives
+ * carrying the aggregate's empty-input value, which the replacement reproduces
+ * byte-for-byte), so three-valued predicate logic is preserved with no new code.
+ *
+ * The rewritten Filter's source gains the grouped join's columns; a FilterNode
+ * publishes its source's attributes verbatim, so the result is capped with a bare
+ * pass-through Project (see `capToAttributes`) that re-exposes exactly the
+ * original Filter attributes — without it the extra columns leak to the query
+ * output whenever the Filter is not already under a projection (the common HAVING
+ * shape, where the SELECT list is fused into the Aggregate below the filter).
+ */
+export declare function ruleScalarAggDecorrelationFilter(node: PlanNode, _context: OptContext): PlanNode | null;
+/**
+ * Sort match site: a correlated scalar-aggregate subquery in a SortNode's
+ * sort-key expression — `order by (select count(*) from c where c.fk = o.k)`.
+ * The join stack lands BELOW the Sort (so the sort key can read the grouped
+ * value column), and each recognized subquery reference in the keys is
+ * substituted with the guarded value read; direction/nulls are copied verbatim.
+ *
+ * A SortNode publishes its source's attributes verbatim, so the LEFT join's
+ * appended columns would leak upward and change the row shape every ancestor
+ * sees. The result is therefore capped with the same bare pass-through Project
+ * as the Filter site (`capToAttributes`), re-exposing exactly the Sort's
+ * original attributes — invariant output shape regardless of whether an
+ * enclosing Project exists (view body / compound arm / bare top-level Sort).
+ *
+ * Ordering is stable: the substituted value is byte-identical to the scalar the
+ * subquery would return (same empty-input replacement as the other sites), and
+ * the LEFT join matches at most one row per outer row (unique group keys), so
+ * row count, multiplicity, and per-row sort-key values are all unchanged.
+ */
+export declare function ruleScalarAggDecorrelationSort(node: PlanNode, _context: OptContext): PlanNode | null;
+//# sourceMappingURL=rule-scalar-agg-decorrelation.d.ts.map

package/dist/src/planner/rules/subquery/rule-scalar-agg-decorrelation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-scalar-agg-decorrelation.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/subquery/rule-scalar-agg-decorrelation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAiD,MAAM,0BAA0B,CAAC;AAExG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAgC7D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAahG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAgBzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAoBtG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA0BpG"}