@quereus/quereus 4.3.1 → 4.4.0

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

@@ -0,0 +1,199 @@
+/**
+ * Materialized-view maintenance — plan-tree analysis helpers.
+ *
+ * The stateless utilities the maintenance plan builders lean on: recursive plan-tree
+ * walks (find/count node types, collect table refs + attribute provenance), the
+ * collation/determinism/replicability gates, the create-time rejection diagnostics, and
+ * the single-source scalar-expression evaluator. Split out of
+ * `database-materialized-views.ts` so the manager class and its plan builders read on
+ * their own; every function here is a pure move (no `MaterializedViewManager` state).
+ */
+import { QuereusError } from '../common/errors.js';
+import { type SqlValue, type Row } from '../common/types.js';
+import { BlockNode } from '../planner/nodes/block.js';
+import { PlanNode, type ScalarPlanNode, type RowDescriptor, type RelationalPlanNode } from '../planner/nodes/plan-node.js';
+import { TableReferenceNode } from '../planner/nodes/reference.js';
+import { TableFunctionCallNode } from '../planner/nodes/table-function-call.js';
+import { PlanNodeType } from '../planner/nodes/plan-node-type.js';
+import type { MaintainedTableSchema } from '../schema/derivation.js';
+import type { Database } from './database.js';
+import type { MaintenancePlan } from './database-materialized-views-plans.js';
+/** True for the default (binary) collation: an absent name or a case-insensitive
+ *  `BINARY`. Non-binary collations gate off the prefix-scan fast path (see
+ *  {@link MaterializedViewManager.tryBuildCoveringPrefix}). */
+export declare function isBinaryCollation(collation: string | undefined): boolean;
+/** Canonical upper-case collation name (absent ⇒ `BINARY`). Used to compare a backing-PK
+ *  column's collation against its source PK column's at plan-build (see
+ *  {@link MaterializedViewManager.buildLateralTvfPrefixDeletePlan}). */
+export declare function normalizeCollation(collation: string | undefined): string;
+export declare function mvKey(schemaName: string, name: string): string;
+/** Every source base (lowercased `schema.table`) a plan must be indexed under in
+ *  `rowTimeBySource`. Single-source arms read one base; the 1:1-join arm also reads
+ *  the lookup base, so a write to `P` fires maintenance too; the full-rebuild floor reads
+ *  every source its body touches (set-op legs, all join sources). */
+export declare function planSourceBases(plan: MaintenancePlan): string[];
+/** Walk the whole plan; return the string form of the first non-deterministic scalar
+ *  expression (a `random()`/`now()`/volatile UDF, anywhere in the body), or `undefined`
+ *  when the body is fully deterministic. The full-rebuild floor's whole-body determinism
+ *  gate uses this — a non-deterministic body can never be kept equal to its plain view.
+ *  `physical.deterministic` is computed lazily and propagates from leaves, so checking each
+ *  scalar node is sound on either the pre-physical or optimized plan. */
+export declare function findNonDeterministic(node: PlanNode): string | undefined;
+/** Walk the whole plan; return the NAME of the first function whose schema is not declared
+ *  REPLICABLE (bit-identical across peers/platforms/app-versions — built-ins auto-qualify),
+ *  or `undefined` when every function in the body qualifies. Mirrors {@link findNonDeterministic}'s
+ *  `getChildren()` recursion so nested calls (a UDF inside a builtin inside a UDF) and the
+ *  WHERE / GROUP BY / aggregate-arg / TVF-arg positions are all reached. The structural
+ *  `'functionSchema' in node` test covers all four function-bearing node kinds uniformly —
+ *  scalar (`function.ts`), aggregate (`aggregate-function.ts`), TVF call
+ *  (`table-function-call.ts`), and TVF reference (`reference.ts`) — without per-type imports.
+ *  Window functions live in a separate builtin-only registry with no UDF registration path and
+ *  carry no scalar/aggregate/TVF `functionSchema` on these nodes, so they are inherently
+ *  replicable and are never flagged. Consumed only when the backing host declares
+ *  `requiresReplicableDerivations` (see {@link MaterializedViewManager.buildMaintenancePlan}). */
+export declare function findNonReplicableFunction(node: PlanNode): string | undefined;
+/**
+ * The collation analogue of {@link findNonReplicableFunction}: return the NAME of the
+ * first collation that governs derived bytes and is neither built-in nor declared
+ * REPLICABLE, or `undefined` when every collation qualifies. Two sources, soundness-first
+ * (any non-builtin non-replicable collation anywhere rejects — see the soundness note in
+ * `replicable-collation-class`):
+ *
+ *  1. **Body scalars** — every fold/order/key site (explicit `COLLATE`, a declared/default
+ *     column collation, a comparison's effective collation, ORDER BY / GROUP BY / DISTINCT
+ *     keys) resolves through some scalar node whose `getType().collationName` carries the
+ *     name. One `getChildren()` walk reading that field uniformly reaches them all, including
+ *     nested COLLATE, subquery/CTE/set-op legs, and MV-over-MV bodies (whose source columns
+ *     carry the producing backing's published collation).
+ *  2. **Backing key** — a custom collation can govern the backing key MERGE without appearing
+ *     on any body scalar type (a maintained table declared with an explicit
+ *     `UNIQUE (… COLLATE custom)` or PK collation the SELECT body never names). The body walk
+ *     alone would miss it, so the maintained table's own PK column collations + declared
+ *     secondary UNIQUE per-column enforcement collations (resolving an index-derived override
+ *     via {@link uniqueEnforcementCollations}) are checked directly — the robust closure.
+ *
+ * Consumed only when the backing host declares `requiresReplicableDerivations`.
+ */
+export declare function findNonReplicableCollation(node: PlanNode, mv: MaintainedTableSchema, db: Database): string | undefined;
+/** Canonical, order-stable, bigint-safe string for a key tuple — used to dedup the
+ *  distinct affected backing keys of a single change in the residual-recompute arm. */
+export declare function canonKeyValues(values: readonly SqlValue[]): string;
+/** Structural view of an aggregate node shared by the logical/physical variants. */
+export interface AggregateLike {
+    readonly groupBy: readonly ScalarPlanNode[];
+    readonly aggregates: readonly {
+        readonly expression: ScalarPlanNode;
+    }[];
+}
+/** Find the first aggregate node anywhere in the plan. */
+export declare function findAggregate(node: PlanNode): AggregateLike | undefined;
+/** True if any node in the plan has the given type (recursive `getChildren` walk). */
+export declare function containsNodeType(node: PlanNode, type: PlanNodeType): boolean;
+/** True if the plan carries any join node (logical or physical). Used by the
+ *  row-time gate, which is single-source — any join is ineligible. */
+export declare function containsAnyJoin(node: PlanNode): boolean;
+/** Count nodes of the given type (recursive `getChildren` walk). Used by the
+ *  lateral-TVF gate to reject nested/multiple TVFs. */
+export declare function countNodeType(node: PlanNode, type: PlanNodeType): number;
+/** Count join nodes (logical + physical) in the plan — used to reject a chained
+ *  lateral join (the admitted lateral-TVF shape carries exactly one). */
+export declare function countJoins(node: PlanNode): number;
+/** Find the first {@link TableFunctionCallNode} anywhere in the plan, or `undefined`. */
+export declare function findTableFunctionCall(node: PlanNode): TableFunctionCallNode | undefined;
+/** Collect `relationKey → TableReferenceNode` over a plan. */
+export declare function collectTableRefs(node: PlanNode, out?: Map<string, TableReferenceNode>): Map<string, TableReferenceNode>;
+/**
+ * Merge attribute provenance (output attr id → producing scalar expr) from every
+ * node that exposes it. Physical aggregates expose `getProducingExprs()`; the
+ * logical {@link AggregateNode} present in the pre-physical analyzed plan does
+ * not, so its group-by → output-attr mapping is reconstructed directly here.
+ */
+export declare function collectProducingExprs(node: PlanNode, out?: Map<number, ScalarPlanNode>): Map<number, ScalarPlanNode>;
+/**
+ * Transitive provenance: chase an output-attr → producing `ColumnReference` chain (a
+ * Project-over-Aggregate or a passthrough-through-Join adds a hop the single-hop
+ * {@link resolveSourceCol} cannot follow) until landing on a base-source column, or
+ * `undefined` (e.g. a TVF-output column with no base-source identity). Shared by the
+ * aggregate-residual and lateral-TVF arms.
+ */
+export declare function resolveTransitiveSourceCol(attrId: number, sourceAttrToCol: Map<number, number>, producingByAttrId: Map<number, ScalarPlanNode>): number | undefined;
+/**
+ * True iff the analyzed join body's WHERE references the lookup table `P` (or any base other
+ * than the driving `T`) — the classification the join-residual arm uses to decide whether the
+ * lookup side must be delete-capable (see {@link MaterializedViewManager.buildJoinResidualPlan}).
+ * The body WHERE — possibly split by predicate-pushdown — surfaces as one or more
+ * {@link FilterNode}s above/around the join; the join's own `ON` condition lives inside the
+ * JoinNode (not a Filter) and so is excluded. Each column a filter predicate references is
+ * resolved against `T`'s attribute→source-column map (transitively); a reference that does NOT
+ * resolve to a `T` column is a `P` (the arm requires exactly two base refs, `T` and `P`) — or
+ * otherwise non-`T` — reference. Conservative by construction: an unresolved reference counts as
+ * lookup-referencing, so the cheaper `T`-only upsert-only path is taken only when **every**
+ * filter column provably belongs to `T`.
+ */
+export declare function bodyWhereReferencesLookup(analyzed: BlockNode, tAttrToCol: Map<number, number>, producingByAttrId: Map<number, ScalarPlanNode>): boolean;
+/**
+ * True iff any {@link FilterNode} predicate in the body (the body WHERE) is non-deterministic.
+ * The join-residual arm embeds the body WHERE in every residual (forward, in-scope reverse, and
+ * — when delete-capable — membership), so a volatile predicate (`random()`/`now()`/a volatile
+ * UDF) would make them irreproducible and diverge from the plain view. The arm therefore declines
+ * such a body (returns `null` → the full-rebuild floor, which applies the **pragma-gated**
+ * whole-body determinism reject — rejected without `pragma nondeterministic_schema`, accepted as a
+ * wholesale rebuild with it), preserving the pre-WHERE-widening behavior rather than building an
+ * unsound bounded-delta residual.
+ */
+export declare function bodyWhereIsNonDeterministic(analyzed: BlockNode): boolean;
+/** Read the output attributes of a block's final relational statement. */
+export declare function relationalAttributes(block: BlockNode): ReturnType<TableReferenceNode['getAttributes']> | undefined;
+/** The root relational node of a block's final relational statement — the node whose
+ *  attributes {@link relationalAttributes} reads — or `undefined`. Feeds the shared
+ *  coverage-prover join predicates ({@link proveOneToOneJoin}) for the join-residual arm. */
+export declare function rootRelationalNode(block: BlockNode): RelationalPlanNode | undefined;
+/**
+ * The diagnostic for a create-time **hard** reject — one of the four non-shape rejections
+ * the cost-gated-with-floor model keeps (non-determinism, bag/no-key, no relational output,
+ * size). Names the MV and steers to a plain `view` (live re-evaluation) or
+ * `create table ... as <body>` (a one-off snapshot) — never a refresh policy, never an
+ * internal implementation detail. Used by the arm builders (for their arm-specific
+ * determinism diagnostic) and by {@link MaterializedViewManager.buildFullRebuildPlan}.
+ */
+export declare function cannotMaterialize(mvName: string, detail: string): QuereusError;
+/**
+ * The diagnostic for the create-time **replicable-determinism** reject — distinct from
+ * {@link cannotMaterialize} because the fix here is not "use a plain view": the body is
+ * fine, it just calls a function the backing host requires be REPLICABLE. So this names the
+ * function and steers to declaring it `replicable: true` at registration (built-ins qualify
+ * automatically). Fires only when the resolved backing host declares
+ * `requiresReplicableDerivations`. `StatusCode.UNSUPPORTED`.
+ */
+export declare function nonReplicableDerivationError(mvName: string, fnName: string): QuereusError;
+/**
+ * The diagnostic for the create-time **replicable-collation** reject — the collation
+ * analogue of {@link nonReplicableDerivationError}. The body is fine; it just folds or
+ * orders (comparison / ORDER BY / GROUP BY / DISTINCT / backing key) under a collation the
+ * backing host requires be bit-identical across peers — so this does NOT steer to a plain
+ * view. It names the collation and steers to declaring it `replicable: true` at registration
+ * (built-in collations qualify automatically). Fires only when the resolved backing host
+ * declares `requiresReplicableDerivations`. `StatusCode.UNSUPPORTED`.
+ */
+export declare function nonReplicableCollationDerivationError(mvName: string, collationName: string): QuereusError;
+/**
+ * True iff a computed projection expression can be evaluated as a pure function of the
+ * changed source row — i.e. it contains no subquery / relational subtree (cross-row) and
+ * every column reference resolves to a source column (no correlated / outer reference).
+ * This is the "shape" gate distinct from the determinism gate (a determinism failure is
+ * caught earlier by `checkDeterministic`); a `false` here is a `null` fall-through to the
+ * full-rebuild floor, not a hard reject.
+ */
+export declare function isSingleRowEvaluable(expr: ScalarPlanNode, sourceDescriptor: RowDescriptor): boolean;
+/**
+ * Compile a deterministic scalar plan node into a per-source-row evaluator by reusing
+ * the runtime: emit the node once, then run it against a row context that maps each
+ * source attribute id to its column index in the changed row. Reusing the runtime
+ * (rather than a hand-rolled scalar interpreter) guarantees a computed backing value is
+ * byte-for-byte what `select <body>` would produce — the materialized-view ≡ view
+ * contract. The gated forms (deterministic scalars over a single row, no subqueries —
+ * see {@link assertSingleRowEvaluable}) resolve synchronously; a Promise result would
+ * signal an unsupported async form and is surfaced loudly rather than silently awaited.
+ */
+export declare function compileSourceRowEvaluator(db: Database, expr: ScalarPlanNode, sourceDescriptor: RowDescriptor): (row: Row) => SqlValue;
+//# sourceMappingURL=database-materialized-views-analysis.d.ts.map

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

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