@quereus/quereus 4.21.1 → 4.23.0

package/dist/src/core/database-cardinality-feedback.d.ts

@@ -0,0 +1,259 @@
+/**
+ * The observed row-count overlay: exact base-table sizes seen during execution.
+ *
+ * One per `Database`. The planner reads it through `plannedRowCount`
+ * (`planner/stats/table-cardinality.ts`), where an answering entry outranks the
+ * catalog's `ANALYZE` count and a module's approximate count, but not a module's
+ * exact one, and through `plannedRowsPerKey`, where an entry's rows per key answers
+ * unless the catalog's statistics cover the column set. This module owns the record
+ * policy — which observations are worth keeping, and when one has moved far enough
+ * from what plans were costed against to call it a *shift* — and the entries' lifetime.
+ *
+ * Validity is schema identity: an entry answers only for the exact `TableSchema`
+ * object it was observed under. Any swap (`ANALYZE`, `ALTER TABLE`, drop and
+ * re-create) silences it, and a schema-change listener evicts it. The identity
+ * check is the correctness guard; the listener is memory hygiene.
+ *
+ * An entry holds an exact count from a complete read, a floor ("at least N rows") from a
+ * partial one, or both; a floor only ever raises an estimate, and an exact count clears it.
+ * Beside them it keeps, per equality column set the table is seeked on through a
+ * non-unique index, a running mean of the rows one key matched ({@link PerKeyEntry}).
+ *
+ * Execution feeds it through {@link CardinalityFeedbackManager.publish}, which admits
+ * only observations of committed state: one made inside a transaction is held until
+ * that transaction commits ({@link CardinalityFeedbackManager.onCommitted}) and
+ * dropped if it rolls back ({@link CardinalityFeedbackManager.onRolledBack}).
+ *
+ * A shift reaches prepared statements through `onShift`; each statement paces its
+ * re-plans with a {@link FeedbackReplanState}. A module-reported size, which moves with
+ * no observation at all, is re-checked by each statement at execution start against the
+ * size its plan was costed with ({@link ReportedSizeSnapshot}).
+ *
+ * Nothing here is persisted: a new `Database` starts empty. See
+ * docs/progressive-optimizer.md §3.2–3.6.
+ */
+import type { OptimizerTuning } from '../planner/optimizer-tuning.js';
+import { CardinalityObservations, type RowsPerKeySpec } from '../runtime/cardinality-observations.js';
+import { type ObservedKeyCardinalities, type ObservedRowCount, type ObservedRowCounts } from '../planner/stats/table-cardinality.js';
+import type { SchemaDependency } from '../planner/planning-context.js';
+import type { TableSchema } from '../schema/table.js';
+import type { Database } from './database.js';
+import type { ModuleRowCount } from '../vtab/module.js';
+/** Database internals the manager needs — keeps it constructible without the full `Database`. */
+export interface CardinalityFeedbackManagerContext {
+    readonly schemaManager: Database['schemaManager'];
+    /** Read on every record, so `Database.updateOptimizerTuning` takes effect immediately. */
+    getTuning(): OptimizerTuning;
+    /** True when no transaction (explicit or implicit) is open. */
+    getAutocommit(): boolean;
+    /** The table's module's own count (`RowCountSources.reportedRows`), ranked with this overlay's entry. */
+    reportedRows(table: TableSchema): ModuleRowCount | undefined;
+    /**
+     * A recorded count, floor or rows-per-key mean moved at least
+     * `cardinalityFeedback.shiftFactor` away from its baseline: plans costed against the
+     * old number may be wrong. `key` is the lowercased `schema.table` — one key for every
+     * kind, so a per-key shift re-plans every statement reading the table, seeking or not.
+     */
+    onShift(key: string): void;
+}
+/** By-value view of one column set's rows per key, for tests and diagnostics. */
+export interface ObservedRowsPerKeySnapshot {
+    /** Column names, in the order of their sorted indexes. */
+    readonly keyColumns: readonly string[];
+    readonly rowsPerKey: number;
+    readonly samples: number;
+    readonly baselineRowsPerKey: number;
+    readonly shifts: number;
+}
+/** By-value view of one valid entry, for tests and diagnostics. */
+export interface ObservedRowCountSnapshot {
+    readonly schemaName: string;
+    readonly tableName: string;
+    readonly rows: number | undefined;
+    readonly atLeast: number | undefined;
+    /** What the catalog (`ANALYZE`) says for the same table; `undefined` when never analyzed. */
+    readonly catalogRows: number | undefined;
+    readonly baselineRows: number;
+    readonly observations: number;
+    readonly shifts: number;
+    /** Least recently recorded first. */
+    readonly perKey: readonly ObservedRowsPerKeySnapshot[];
+}
+/** The overlay's key for a table: lowercased `schema.table`. Shifts are reported under it. */
+export declare function overlayTableKey(schemaName: string, tableName: string): string;
+/**
+ * One prepared statement's feedback re-plan cooldown (docs/progressive-optimizer.md §3.6).
+ * A shift marks the cached plan; the mark is acted on at an execution start, never
+ * mid-execution. The first feedback re-plan is immediate; re-plan `k + 1` waits until the
+ * statement has executed `cooldown × 2^min(k − 1, 6)` times since re-plan `k` — a mark
+ * arriving sooner stays pending until then.
+ */
+export declare class FeedbackReplanState {
+    private marked;
+    /** Feedback re-plans so far. */
+    private replans;
+    /** Executions started since the last feedback re-plan, the re-planning one included. */
+    private executionsSinceReplan;
+    /** A table the cached plan reads shifted. */
+    markShift(): void;
+    /** The cached plan was dropped for any reason; whatever compiles next reads the current overlay. */
+    onPlanDropped(): void;
+    /** Counts one execution; true when the marked plan must be dropped before it runs. */
+    onExecutionStart(cooldown: number): boolean;
+    private requiredExecutions;
+}
+/**
+ * The planned sizes, as of one compile, of the tables the plan reads whose module reports
+ * its own count (docs/progressive-optimizer.md §3.6). Such a count moves on every write
+ * with no event the planner hears, and a plan that no longer reads the table in full
+ * never produces an observation, so nothing else notices that a table planned at 10 rows
+ * now holds a million. A prepared statement compares its snapshot with the current
+ * planned sizes at each execution start and treats a drift like an overlay shift.
+ *
+ * Planned sizes, not raw module answers, are compared, so an approximate count the
+ * overlay outranks drifts only when what planning would use drifts.
+ */
+export declare class ReportedSizeSnapshot {
+    private readonly sizes;
+    static readonly empty: ReportedSizeSnapshot;
+    private constructor();
+    /**
+     * Called right after a compile, in the same synchronous turn, so each size is the one
+     * the plan's table references were costed with. Tables whose module has no
+     * `getRowCount` are left out: overlay shifts and schema changes already cover them.
+     */
+    static capture(db: Database, dependencies: readonly SchemaDependency[]): ReportedSizeSnapshot;
+    /**
+     * True when some table's planned size has moved `shiftFactor` from the captured one
+     * with the larger side above `minRows` — the overlay's shift rule (§3.4). A table whose
+     * catalog object was replaced is skipped: that schema change already dropped the plan.
+     */
+    drifted(db: Database): boolean;
+}
+export declare class CardinalityFeedbackManager implements ObservedRowCounts, ObservedKeyCardinalities {
+    private readonly ctx;
+    /**
+     * Lowercased `schema.table` → entry, the change-log / work-counter key convention.
+     * `Map` insertion order doubles as recency: a hit or a record re-inserts, so the
+     * first key is the least recently used.
+     */
+    private readonly entries;
+    /**
+     * Observations made inside the open transaction, held until it ends; same key as
+     * `entries`, last count and largest floor per table win. Bounded by the distinct
+     * tables one transaction observes.
+     */
+    private readonly pending;
+    /** {@link onRolledBack} calls so far; each execution's sink records it at start. */
+    private rollbacks;
+    private unsubscribeSchemaChanges;
+    constructor(ctx: CardinalityFeedbackManagerContext);
+    observedRows(table: TableSchema): ObservedRowCount | undefined;
+    /** The running mean for `columns` on `table`, under the same identity rule as {@link observedRows}; a hit refreshes the table's recency. */
+    observedRowsPerKey(table: TableSchema, columns: readonly number[]): number | undefined;
+    /**
+     * Offer one exact row count of `table`, observed by a complete enumeration of
+     * committed state. Applies the record policy (docs/progressive-optimizer.md §3.4):
+     * ignored when the schema object is superseded or when both the observation and the
+     * current estimate are small; otherwise recorded — clearing any floor, which the newer
+     * complete count supersedes — and reported through `onShift` when it has moved
+     * `shiftFactor` from the entry's baseline.
+     */
+    record(table: TableSchema, rows: number): void;
+    /**
+     * Offer one floor for `table`: a read of committed state yielded `rows` distinct rows of
+     * it, so it holds at least that many (docs/progressive-optimizer.md §3.4). Recorded only
+     * when it exceeds both what planning would use now and `minRows`, so a floor never
+     * lowers an estimate and never makes an unknown table look smaller than the default it
+     * plans at today. Shifts like a count; floors only raise, so they cannot oscillate.
+     */
+    recordAtLeast(table: TableSchema, rows: number): void;
+    /**
+     * Offer `count` samples of rows per key for `spec`'s column set on `table`, summing to
+     * `sum` rows — one sample per exhausted equality seek with non-NULL keys
+     * (docs/progressive-optimizer.md §3.4). Ignored under a superseded schema, and unless
+     * the table's planned size exceeds `minRows`: below that every plan finishes fast, and
+     * the gate keeps small-table plans unchanged exactly as the count gate does. So a table
+     * of unknown size learns rows per key only once its size is learned (a complete scan,
+     * a floor, or a module count above the gate); publication applies per-key batches
+     * after the same execution's counts and floors, so one execution can open the gate for
+     * itself. A new column-set entry's baseline is the rows per key the plan was priced
+     * with; the table remembers at most `maxKeySetsPerTable` sets, least recently recorded
+     * evicted. Accepted bias: frequently probed keys weigh more than a uniform sample would.
+     * Reported through `onShift` under the table's key when the folded mean has moved
+     * `shiftFactor` from the set's baseline — the count rule, applied to the mean.
+     */
+    recordRowsPerKey(table: TableSchema, spec: RowsPerKeySpec, sum: number, count: number): void;
+    /**
+     * Offer one finished execution's observations (docs/progressive-optimizer.md §3.5).
+     * A committed read (`readCommitted`) or an execution that ended with no transaction
+     * open saw committed state and is recorded now. Anything else may include the open
+     * transaction's uncommitted writes, so it is held for {@link onCommitted} — unless a
+     * rollback ran during the execution (typically a failing statement's own statement
+     * savepoint, which fires before publication): then a completed scan may have counted
+     * rows that no longer exist, and the whole execution is discarded.
+     */
+    publish(observations: CardinalityObservations, options: {
+        readCommitted: boolean;
+    }): void;
+    /**
+     * A fresh per-execution sink, stamped so {@link publish} can tell whether a rollback ran
+     * under it, and carrying the record floor so it can drop floors that could never record.
+     */
+    beginObservations(): CardinalityObservations;
+    /**
+     * The open transaction committed: record what it held, except tables it wrote.
+     * Such an observation was made mid-transaction, possibly before later writes in the
+     * same transaction, and the change log cannot say which came first. `changedCounts` is
+     * the change log keyed like `entries` — every table the transaction wrote, even one
+     * whose writes cancelled out — and is not built when nothing is held.
+     */
+    onCommitted(changedCounts: () => Map<string, number>): void;
+    /** The open transaction, or some of its work, was undone: forget everything held. */
+    onRolledBack(): void;
+    /** Forget every observation, held ones included; later compiles read the catalog only. */
+    clear(): void;
+    /** Valid entries, by value, least recently used first. Does not refresh recency. */
+    snapshot(): ObservedRowCountSnapshot[];
+    dispose(): void;
+    private subscribeToSchemaChanges;
+    /**
+     * Exact counts first: a floor at or below the count just recorded is then ignored.
+     * Rows per key last, so a count or floor from the same execution can open its table-size gate.
+     */
+    private recordAll;
+    private holdAll;
+    /** What is held for `table`; anything held under an older schema object for its name is superseded. */
+    private held;
+    /** As {@link recordAll}: the count first, so a floor it already covers is ignored, and rows per key last. */
+    private recordHeld;
+    private isSuperseded;
+    /**
+     * What planning would use for `table` right now — `existing` ranked with the module's
+     * count and the catalog's (§3.3), else the default — so an exactly module-sized table
+     * compares against the module and a scan agreeing with it shifts nothing.
+     */
+    private plannedBefore;
+    /** Counts one recorded observation on `entry`, makes it the most recent, and enforces the cap. */
+    private upsert;
+    /** Reports a shift through `onShift` when `rows` has moved `shiftFactor` from the entry's baseline. */
+    private shiftIfMoved;
+    /**
+     * Reports a shift through `onShift` when a column set's mean has moved `shiftFactor`
+     * from its baseline. The table key is reported, not the set: a statement that reads the
+     * table re-plans and every seek node in it re-snapshots the overlay (§3.6). A set's first
+     * record cannot shift when its plan was already priced from the mean (the baseline is what
+     * the plan used); a set re-created after eviction carries the module's estimate again and
+     * may shift once, landing the same plan.
+     */
+    private shiftIfRowsPerKeyMoved;
+    /** The entry under `key` if it was observed against `table`; a stale one is replaced on record. */
+    private validEntry;
+    private touch;
+    /**
+     * Drop least-recently-used entries past the cap. No `onShift`: plans already built
+     * keep their snapshot, and the next compile falls back to catalog or default numbers.
+     */
+    private evictBeyond;
+}
+//# sourceMappingURL=database-cardinality-feedback.d.ts.map

package/dist/src/core/database-cardinality-feedback.d.ts.map

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