@quereus/quereus 4.3.1 → 4.3.2

package/dist/src/core/database-materialized-views-plan-builders.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Materialized-view maintenance — **plan builders**. The cost-gated builder that compiles
+ * an MV body into a {@link MaintenancePlan} (the bounded-delta arms plus the full-rebuild
+ * floor) and the residual-compile / source-stats helpers they share. Extracted from
+ * database-materialized-views.ts as free functions over {@link MaterializedViewManagerContext};
+ * the sole caller in the manager is `registerMaterializedView` → {@link buildMaintenancePlan}.
+ */
+import { BlockNode } from '../planner/nodes/block.js';
+import { TableReferenceNode } from '../planner/nodes/reference.js';
+import { Scheduler } from '../runtime/scheduler.js';
+import { type MaintenanceSourceStats } from '../planner/cost/index.js';
+import type { MaintainedTableSchema } from '../schema/derivation.js';
+import type { TableSchema } from '../schema/table.js';
+import { type AggregateLike } from './database-materialized-views-analysis.js';
+import type { MaterializedViewManagerContext, MaintenancePlan, FullRebuildPlan } from './database-materialized-views-plans.js';
+/**
+ * Build the row-time maintenance plan for an MV — **cost-gated, with a floor, never a
+ * shape allowlist**. The builder tries to match a bounded-delta arm by shape
+ * ({@link tryBuildBoundedDeltaArm}); a body that matches **none** falls through to the
+ * always-correct {@link buildFullRebuildPlan} floor (re-evaluate the whole body, replace
+ * the backing transactionally). **No body is rejected for its shape.** Only five
+ * create-time rejections remain, all non-shape (docs/invariants.md MV-006):
+ *  - a **non-deterministic** body without `pragma nondeterministic_schema` — a hard reject
+ *    in the matched arm (so the arm-specific determinism diagnostic survives) or, for a
+ *    body matching no arm, in the floor's whole-body determinism check;
+ *  - a **bag** (no provable unique key) — the floor's `keysOf` reject (a duplicate-producing
+ *    body usually fails the set contract earlier, at create-fill);
+ *  - a body with **no relational output**;
+ *  - a body that **reads no source table** (`select 42`) — the floor's `sourceBases` reject;
+ *    there is no source to index the plan under and no write that could dirty it;
+ *  - a **full-rebuild-only body over a source past the size threshold**
+ *    ({@link isFullRebuildPathological}, the `materialized_view_rebuild_row_threshold` option).
+ *
+ * The single source may itself be another MV's backing table (an MV-over-MV body):
+ * `building/select.ts` rewrites a reference to `mv1` into a `TableReference` against
+ * `mv1`'s backing table, so the source base is `mv1`'s backing base and the same checks
+ * evaluate against the (keyed `memory`) backing schema unchanged. A write to `mv1` then
+ * drives `mv2` via the cascade in {@link maintainRowTime}.
+ *
+ * Eligibility is a *cost choice* among the body's structurally-sound strategies
+ * ({@link selectMaintenanceStrategy}): the bounded-delta arms are preferred by the argmin
+ * cost gate, and full-rebuild is selected exactly when no bounded-delta arm is sound (an
+ * empty sound set resolves to the floor) — so an existing eligible shape is unaffected.
+ */
+export declare function buildMaintenancePlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema): MaintenancePlan;
+/**
+ * Route the analyzed body to the matching bounded-delta arm, or return `null` when its
+ * shape fits **no** bounded-delta arm (the caller then builds the full-rebuild floor).
+ * Each arm builder likewise returns `null` on a sub-shape mismatch and falls through
+ * here. The arms keep only **determinism** as a hard reject (so their arm-specific
+ * determinism diagnostic survives — see the individual builders); every other mismatch
+ * is a `null` fall-through. Bag / no-output / size rejects live in the floor.
+ */
+export declare function tryBuildBoundedDeltaArm(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode): MaintenancePlan | null;
+/**
+ * Build an `'inverse-projection'` plan for the covering-index shape: a single
+ * row-preserving source `T` with a primary key, a linear
+ * `TableReference → optional Filter → Project → optional Sort` body, a projection that
+ * resolves every source PK column (and every backing-key column) to a **passthrough**
+ * source column — non-key columns may instead be a **deterministic scalar expression**
+ * over the source row — and a partial WHERE evaluable on a single source row. Returns
+ * `null` on any **shape** mismatch (the caller falls through to the full-rebuild floor);
+ * a **non-deterministic** computed column is the one hard reject (its arm-specific
+ * determinism diagnostic must survive rather than fall through to the floor's generic one).
+ */
+export declare function buildInverseProjectionPlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode, tableRef: TableReferenceNode, sourceBase: string): MaintenancePlan | null;
+/**
+ * Build a `'residual-recompute'` plan for a single-source aggregate body
+ * (`select g1,…, agg(…) from T [where P] group by g1,…` over **bare** group columns),
+ * or return `null` on a shape mismatch (the caller falls through to the full-rebuild
+ * floor). Each changed source row belongs to exactly one group `(g1,…)`; maintaining the
+ * MV means recomputing that group's backing row from live state — delete the old slice,
+ * run the group-keyed residual, upsert the recomputed slice (zero rows when the group
+ * emptied). See {@link ResidualRecomputePlan} and `docs/incremental-maintenance.md`
+ * § residual-recompute.
+ *
+ * A **non-deterministic** group/aggregate expression is the one hard reject (the
+ * arm-specific determinism diagnostic must survive); every other mismatch — a scalar
+ * aggregate, a computed group key, a backing key that is not the group key — returns
+ * `null` → the floor.
+ *
+ * NOTE: the group binding is derived **directly** from the aggregate node's bare GROUP
+ * BY columns, not via `extractBindings`. `analyzeRowSpecific`'s `'group'` classification
+ * additionally requires the group key to cover a *source* unique key (so it reports
+ * `'global'` for the common `group by <non-key>` body), which is the wrong test here —
+ * the backing is keyed by the group key regardless of whether it is a source key.
+ */
+export declare function buildAggregateResidualPlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode, tableRef: TableReferenceNode, sourceBase: string, aggregate: AggregateLike): MaintenancePlan | null;
+/**
+ * Build a `'join-residual'` plan for a provably-1:1 row-preserving **inner/cross join**
+ * body (`select … from T join P on T.fk = P.id`), or return `null` on a shape mismatch
+ * (the caller falls through to the full-rebuild floor). The driving table `T` is the one
+ * whose PK the optimizer surfaced as the backing key (the 1:1 join collapses the composite
+ * product key to `T`'s PK); the other base ref is the lookup `P`. See {@link JoinResidualPlan}
+ * and `docs/incremental-maintenance.md` § join-residual.
+ *
+ * Soundness gates (a mismatch on any returns `null` → floor): exactly two base tables; no
+ * aggregate over the join; the backing PK is exactly `T`'s PK projected as passthrough
+ * columns (so each changed `T` row maps to one backing row and the reverse residual's rows
+ * carry the backing key); the join is provably 1:1 on `T` ({@link proveOneToOneJoin} — no
+ * row loss via NOT-NULL FK→PK RI, no fan-out via the join-frame `isUnique(T.pk)`); and the
+ * join is **inner/cross** (an outer join would make the lookup-side reverse residual unsound
+ * — filtering `P` drops the null-extended rows). A **non-deterministic** projection is the
+ * one hard reject (its arm-specific determinism diagnostic must survive).
+ *
+ * **A body WHERE is now accepted** (it is no longer a blanket reject): the predicate is
+ * classified by which base table(s) its columns reference (reusing the per-base-ref
+ * attribute→source-column maps below). A `T`-only predicate needs nothing extra — the
+ * forward residual already carries it and the membership set `{ T : T.fk = P.pk }` cannot
+ * move on a `P` write, so the lookup side stays upsert-only. A predicate referencing `P` (or
+ * both sides) switches the lookup side to a **delete-capable** reverse residual by building
+ * `lookupMembershipResidualScheduler` (the body with the WHERE stripped, keyed on `P`). See
+ * {@link JoinResidualPlan}'s "WHERE handling" note and {@link applyLookupResidual}.
+ */
+export declare function buildJoinResidualPlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode, tableRefs: TableReferenceNode[]): MaintenancePlan | null;
+/**
+ * Compile the **lookup membership** residual for the join-residual arm's delete-capable
+ * lookup side: the MV body with its top-level WHERE **stripped** (membership only) and a
+ * key-equality filter injected on the lookup `P`, keyed `pk0…`. The WHERE is stripped at the
+ * AST level (a shallow clone dropping `where`) and the body re-built + re-analyzed, so only
+ * the WHERE is removed — the join, its `ON` condition, and any projection sub-expressions are
+ * preserved. Re-analysis assigns fresh node ids, so `P`'s reference is re-located by base name
+ * to compute the injection target. Returns `null` if the lookup ref or the key-filter
+ * injection could not be resolved (the caller then falls to the full-rebuild floor).
+ *
+ * Run per affected `P` key, this residual returns **every** `T` row currently joined to `P`
+ * via the join's `ON` condition — irrespective of the WHERE — so {@link applyLookupResidual}
+ * can delete each one's `T.pk` backing key before the in-scope residual re-upserts the
+ * survivors (the membership set the WHERE-bearing reverse residual would otherwise never
+ * shrink).
+ */
+export declare function compileLookupMembershipResidual(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, lookupBase: string, pPkCols: readonly number[]): Scheduler | null;
+/**
+ * Build a `'full-rebuild'` plan — the always-correct floor — for an MV whose body matches
+ * no bounded-delta arm, or throw with a non-shape diagnostic. This is the fall-through
+ * builder {@link tryBuildBoundedDeltaArm} routes to on a `null` (no bounded-delta arm fits).
+ * See {@link FullRebuildPlan} and `docs/mv-maintenance.md` § Full-rebuild floor /
+ * § Primary key inference.
+ *
+ * Create-time rejections (none shape-based — the floor accepts general bodies):
+ * - **bag** body with no provable unique key (`keysOf` over the optimized body root is
+ *   empty) — there is no row identity to materialize on. `keysOf` already gates its
+ *   all-columns fallback on `isSet`, so a non-empty result is a real key (a true column
+ *   key OR the all-columns key of a provable set) and an empty result is exactly a bag.
+ *   (A duplicate-producing body usually fails the set contract earlier, at create-fill.)
+ * - **non-deterministic** body (any `random()`/`now()`/volatile UDF anywhere in the plan)
+ *   without `pragma nondeterministic_schema` — no maintenance could keep it equal to its
+ *   plain view (mirrors the per-arm determinism rejects and the DDL determinism gate);
+ * - body with **no relational output** (degenerate);
+ * - **size**: full-rebuild is the only sound strategy *and* the **largest** participating
+ *   source exceeds the `materialized_view_rebuild_row_threshold` option
+ *   ({@link isFullRebuildPathological}) — every DML write would re-scan that source.
+ *   `0` disables the size reject (accept any size).
+ */
+export declare function buildFullRebuildPlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode): FullRebuildPlan;
+/**
+ * Compile the key-filtered residual for a binding into a reusable {@link Scheduler}:
+ * the analyzed body with a key-equality filter injected on `T`'s `TableReferenceNode`
+ * (parameterized `${paramPrefix}0…`), then optimized + emitted. Mirrors the assertion
+ * evaluator's residual compilation (`database-assertions.ts`) so the two cannot drift.
+ * Returns `null` if `injectKeyFilter` could not target `T` (the arm builder then falls
+ * through to the full-rebuild floor).
+ */
+export declare function compileResidual(ctx: MaterializedViewManagerContext, analyzed: BlockNode, relKey: string, bindColumns: readonly number[], paramPrefix: 'gk' | 'pk'): Scheduler | null;
+/**
+ * Build a `'prefix-delete'` plan for a single-source lateral-TVF fan-out body
+ * (`select T.pk…, …, f.* from T cross join lateral tvf(<args over T>) f`), or return
+ * `null` on a shape mismatch (the caller falls through to the full-rebuild floor). The
+ * backing PK is the composite product key `(T.pk ∪ tvf-key)` that `keysOf` advertises
+ * through the lateral join; the base PK is its leading prefix. See {@link PrefixDeletePlan}
+ * and `docs/incremental-maintenance.md` § prefix-delete.
+ *
+ * Soundness gates (a mismatch on any returns `null` → floor): exactly one lateral TVF and
+ * one join (no nested/multi TVF, no aggregate over the fan-out); the TVF advertises a
+ * per-call key; the base PK projected and forming the **leading prefix** of the backing PK
+ * with a non-empty TVF-key tail (so each base row's fan-out rows are individually
+ * addressable and a by-prefix delete selects exactly one base row's slice). An `order by`
+ * over the fan-out that reorders the composite key so the base PK no longer leads is a
+ * `null` fall-through (the floor maintains it wholesale). The body's WHERE, if any, is part
+ * of the residual (so an out-of-scope base row fans out to zero rows), exactly as in the
+ * aggregate arm. A **non-deterministic** TVF / argument is the one hard reject (its
+ * arm-specific determinism diagnostic must survive).
+ */
+export declare function buildLateralTvfPrefixDeletePlan(ctx: MaterializedViewManagerContext, mv: MaintainedTableSchema, analyzed: BlockNode, tableRef: TableReferenceNode, sourceBase: string): MaintenancePlan | null;
+/**
+ * Assemble {@link MaintenanceSourceStats} for the cost gate from the optimizer's
+ * StatsProvider and tuning. `tableRows` / `distinctGroupsEstimate` come from the
+ * provider (heuristic defaults when absent); `forwardBodyCost` is estimated from the
+ * forward cost helpers (a scan + optional filter + projection of the source — the
+ * covering-index body shape); `fallbackRatio` carries the detection kernel's
+ * `deltaPerRowFallbackRatio` for the no-stats residual path.
+ */
+/**
+ * The CURRENT `TableSchema` of a source `TableReferenceNode`, re-resolved through the
+ * schema manager. A plan node captures the schema as of plan-build; a later `analyze`
+ * replaces the catalog entry with one carrying fresh `statistics`, so the stale captured
+ * schema would report pre-`analyze` row counts. Re-resolving keeps the floor's size gate
+ * on the live source size. Falls back to the node's captured schema if the name no longer
+ * resolves (it always should — the body planned).
+ */
+export declare function liveSourceSchema(ctx: MaterializedViewManagerContext, ref: TableReferenceNode): TableSchema;
+export declare function estimateMaintenanceStats(ctx: MaterializedViewManagerContext, sourceSchema: TableSchema, projectionCount: number, hasPredicate: boolean): MaintenanceSourceStats;
+//# sourceMappingURL=database-materialized-views-plan-builders.d.ts.map

package/dist/src/core/database-materialized-views-plan-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-materialized-views-plan-builders.d.ts","sourceRoot":"","sources":["../../../src/core/database-materialized-views-plan-builders.ts"],"names":[],"mappings":"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"}