@harperfast/harper 5.2.0-alpha.6 → 5.2.0-beta.2

package/dist/sqlEngine/logical/op.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Logical operators.
+ *
+ * The logical plan is a tree of these nodes produced by logical/build.ts from
+ * the bound IR and rewritten by optimizer/rules/* before being lowered to a
+ * physical plan in physical/plan.ts.
+ */
+import type { ExprNode, ProjectionNode, SortNode, TableRefNode } from '../parser/ast.ts';
+import type { BoundTable } from '../binder/bind.ts';
+export type LogicalPlan = LogicalScan | LogicalFilter | LogicalProject | LogicalJoin | LogicalAggregate | LogicalSort | LogicalLimit | LogicalDistinct | LogicalInsert | LogicalUpdate | LogicalDelete;
+export interface LogicalScan {
+    kind: 'Scan';
+    table: TableRefNode;
+    boundTable?: BoundTable;
+    /**
+     * Set in join queries: the canonical alias this scan's rows are qualified by
+     * (`<alias>.<attr>`). Undefined for single-table queries (bare-keyed rows).
+     */
+    alias?: string;
+    pushedFilter?: ExprNode;
+    pushedSort?: SortNode[];
+    pushedLimit?: {
+        limit?: number;
+        offset?: number;
+    };
+    projection?: string[];
+    residualFilter?: ExprNode;
+    /**
+     * Set when this scan is the inner side of an index-nested-loop join: it is
+     * re-probed per outer row via an equality on `keyAttribute` (which must be
+     * indexed), so validateScannable treats it as index-served rather than a
+     * standalone full scan.
+     */
+    joinProbe?: {
+        keyAttribute: string;
+    };
+}
+export interface LogicalFilter {
+    kind: 'Filter';
+    input: LogicalPlan;
+    predicate: ExprNode;
+}
+export interface LogicalProject {
+    kind: 'Project';
+    input: LogicalPlan;
+    projections: ProjectionNode[];
+}
+export interface LogicalJoin {
+    kind: 'Join';
+    left: LogicalPlan;
+    right: LogicalPlan;
+    on?: ExprNode;
+    type: 'inner' | 'left' | 'cross';
+    strategy?: 'relationship' | 'indexNL' | 'hash' | 'nestedLoop';
+}
+export interface LogicalAggregate {
+    kind: 'Aggregate';
+    input: LogicalPlan;
+    groupKeys: ExprNode[];
+    aggs: {
+        name: string;
+        arg: ExprNode | {
+            kind: 'star';
+        };
+        outputName: string;
+        distinct?: boolean;
+    }[];
+    having?: ExprNode;
+}
+export interface LogicalSort {
+    kind: 'Sort';
+    input: LogicalPlan;
+    keys: SortNode[];
+}
+export interface LogicalLimit {
+    kind: 'Limit';
+    input: LogicalPlan;
+    limit?: number;
+    offset?: number;
+}
+export interface LogicalDistinct {
+    kind: 'Distinct';
+    input: LogicalPlan;
+    keys?: ExprNode[];
+}
+export interface LogicalInsert {
+    kind: 'Insert';
+    table: TableRefNode;
+    rows: ExprNode[][] | LogicalPlan;
+    columns: string[];
+}
+export interface LogicalUpdate {
+    kind: 'Update';
+    table: TableRefNode;
+    assignments: {
+        column: string;
+        expr: ExprNode;
+    }[];
+    selector: LogicalPlan;
+}
+export interface LogicalDelete {
+    kind: 'Delete';
+    table: TableRefNode;
+    selector: LogicalPlan;
+}

package/dist/sqlEngine/logical/op.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Logical operators.
+ *
+ * The logical plan is a tree of these nodes produced by logical/build.ts from
+ * the bound IR and rewritten by optimizer/rules/* before being lowered to a
+ * physical plan in physical/plan.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=op.js.map

package/dist/sqlEngine/logical/op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.js","sourceRoot":"","sources":["../../../sqlEngine/logical/op.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/sqlEngine/optimizer/joinAnalysis.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared analysis of a LogicalJoin's ON clause, used by both the join-strategy
+ * rule (optimizer/rules/planJoins.ts) and the physical planner (physical/plan).
+ *
+ * In a left-deep tree the right child is always a single base table (a Scan,
+ * optionally wrapped in a Filter for its own single-table WHERE conjuncts). We
+ * split the ON predicate into:
+ *   - equi-pairs `outer = inner`, where `inner` references only the right
+ *     table's alias and `outer` references only left-side aliases;
+ *   - a residual predicate (non-equi conditions, or equalities that don't cleanly
+ *     separate across the join boundary) applied on the merged row.
+ */
+import type { ExprNode } from '../parser/ast.ts';
+import type { LogicalJoin, LogicalScan } from '../logical/op.ts';
+export interface EquiPair {
+    outer: ExprNode;
+    inner: ExprNode;
+}
+export interface JoinAnalysis {
+    rightAlias: string;
+    rightScan: LogicalScan;
+    equiPairs: EquiPair[];
+    residualOn?: ExprNode;
+}
+/** Unwraps the right child to its base Scan (through any stacked Filters). */
+export declare function rightBaseScan(join: LogicalJoin): LogicalScan | null;
+export declare function analyzeJoin(join: LogicalJoin): JoinAnalysis | null;
+/**
+ * Picks the equi-pair to drive an index-nested-loop probe: its inner operand is
+ * a plain column on the right table that is indexed. Returns null when no
+ * equi-pair qualifies (caller falls back to hash / nested-loop).
+ */
+export declare function pickIndexedProbe(analysis: JoinAnalysis): {
+    pair: EquiPair;
+    attribute: string;
+} | null;
+export declare function referencedAliases(expr: ExprNode, out?: Set<string>): Set<string>;

package/dist/sqlEngine/optimizer/joinAnalysis.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Shared analysis of a LogicalJoin's ON clause, used by both the join-strategy
+ * rule (optimizer/rules/planJoins.ts) and the physical planner (physical/plan).
+ *
+ * In a left-deep tree the right child is always a single base table (a Scan,
+ * optionally wrapped in a Filter for its own single-table WHERE conjuncts). We
+ * split the ON predicate into:
+ *   - equi-pairs `outer = inner`, where `inner` references only the right
+ *     table's alias and `outer` references only left-side aliases;
+ *   - a residual predicate (non-equi conditions, or equalities that don't cleanly
+ *     separate across the join boundary) applied on the merged row.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rightBaseScan = rightBaseScan;
+exports.analyzeJoin = analyzeJoin;
+exports.pickIndexedProbe = pickIndexedProbe;
+exports.referencedAliases = referencedAliases;
+/** Unwraps the right child to its base Scan (through any stacked Filters). */
+function rightBaseScan(join) {
+    let node = join.right;
+    // Rules may layer more than one Filter; unwrap them all.
+    while (node.kind === 'Filter')
+        node = node.input;
+    return node.kind === 'Scan' ? node : null;
+}
+function analyzeJoin(join) {
+    const rightScan = rightBaseScan(join);
+    if (!rightScan || !rightScan.alias)
+        return null;
+    const rightAlias = rightScan.alias;
+    const equiPairs = [];
+    const residuals = [];
+    for (const conjunct of flattenAnd(join.on)) {
+        const pair = asEquiPair(conjunct, rightAlias);
+        if (pair)
+            equiPairs.push(pair);
+        else
+            residuals.push(conjunct);
+    }
+    return {
+        rightAlias,
+        rightScan,
+        equiPairs,
+        residualOn: residuals.length > 0 ? andAll(residuals) : undefined,
+    };
+}
+/**
+ * Picks the equi-pair to drive an index-nested-loop probe: its inner operand is
+ * a plain column on the right table that is indexed. Returns null when no
+ * equi-pair qualifies (caller falls back to hash / nested-loop).
+ */
+function pickIndexedProbe(analysis) {
+    const attrs = analysis.rightScan.boundTable?.attributes ?? [];
+    for (const pair of analysis.equiPairs) {
+        if (pair.inner.kind === 'column' && pair.inner.table === analysis.rightAlias) {
+            const attr = attrs.find((a) => a.name === pair.inner.name);
+            if (attr?.indexed)
+                return { pair, attribute: pair.inner.name };
+        }
+    }
+    return null;
+}
+function asEquiPair(expr, rightAlias) {
+    if (expr.kind !== 'binop' || expr.op !== '=')
+        return null;
+    const leftAliases = referencedAliases(expr.left);
+    const rightAliases = referencedAliases(expr.right);
+    // One operand must reference only the right table; the other only left-side
+    // table(s) (and at least one — a literal isn't a join key).
+    if (onlyAlias(rightAliases, rightAlias) && leftAliases.size > 0 && !leftAliases.has(rightAlias)) {
+        return { outer: expr.left, inner: expr.right };
+    }
+    if (onlyAlias(leftAliases, rightAlias) && rightAliases.size > 0 && !rightAliases.has(rightAlias)) {
+        return { outer: expr.right, inner: expr.left };
+    }
+    return null;
+}
+function onlyAlias(aliases, alias) {
+    return aliases.size === 1 && aliases.has(alias);
+}
+function flattenAnd(expr) {
+    if (!expr)
+        return [];
+    if (expr.kind === 'logical' && expr.op === 'and')
+        return expr.args.flatMap(flattenAnd);
+    return [expr];
+}
+function andAll(exprs) {
+    return exprs.length === 1 ? exprs[0] : { kind: 'logical', op: 'and', args: exprs };
+}
+function referencedAliases(expr, out = new Set()) {
+    switch (expr.kind) {
+        case 'column':
+            if (expr.table)
+                out.add(expr.table);
+            return out;
+        case 'binop':
+            referencedAliases(expr.left, out);
+            referencedAliases(expr.right, out);
+            return out;
+        case 'logical':
+            expr.args.forEach((a) => referencedAliases(a, out));
+            return out;
+        case 'in':
+            referencedAliases(expr.expr, out);
+            if (Array.isArray(expr.list))
+                expr.list.forEach((e) => referencedAliases(e, out));
+            return out;
+        case 'between':
+            referencedAliases(expr.expr, out);
+            referencedAliases(expr.low, out);
+            referencedAliases(expr.high, out);
+            return out;
+        case 'like':
+            referencedAliases(expr.expr, out);
+            referencedAliases(expr.pattern, out);
+            return out;
+        case 'isNull':
+            referencedAliases(expr.expr, out);
+            return out;
+        case 'funcCall':
+            expr.args.forEach((a) => referencedAliases(a, out));
+            return out;
+        case 'aggCall':
+            if (expr.arg.kind !== 'star')
+                referencedAliases(expr.arg, out);
+            return out;
+        case 'case':
+            for (const c of expr.cases) {
+                referencedAliases(c.when, out);
+                referencedAliases(c.then, out);
+            }
+            if (expr.else)
+                referencedAliases(expr.else, out);
+            return out;
+        case 'cast':
+            referencedAliases(expr.expr, out);
+            return out;
+        default:
+            return out;
+    }
+}
+//# sourceMappingURL=joinAnalysis.js.map

package/dist/sqlEngine/optimizer/joinAnalysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joinAnalysis.js","sourceRoot":"","sources":["../../../sqlEngine/optimizer/joinAnalysis.ts"],"names":[],"mappings":"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"}

package/dist/sqlEngine/optimizer/optimize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Driver for phase-1 optimizer rules.
+ *
+ * The order here matters: predicate normalization happens first so other
+ * rules see the canonical form; predicate pushdown then lifts the predicate
+ * into the scan; sort-from-index inspects the bound table's index list to
+ * decide whether the sort can be served by Table.search; limit pushdown
+ * finally folds limit/offset into the scan; projection pushdown computes the
+ * minimal attribute set; validateScannable enforces "no full scan without
+ * opt-in".
+ */
+import type { LogicalPlan } from '../logical/op.ts';
+export declare function optimize(plan: LogicalPlan): LogicalPlan;

package/dist/sqlEngine/optimizer/optimize.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Driver for phase-1 optimizer rules.
+ *
+ * The order here matters: predicate normalization happens first so other
+ * rules see the canonical form; predicate pushdown then lifts the predicate
+ * into the scan; sort-from-index inspects the bound table's index list to
+ * decide whether the sort can be served by Table.search; limit pushdown
+ * finally folds limit/offset into the scan; projection pushdown computes the
+ * minimal attribute set; validateScannable enforces "no full scan without
+ * opt-in".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optimize = optimize;
+const ruleEngine_ts_1 = require("./ruleEngine.js");
+const predicatePushdown_ts_1 = require("./rules/predicatePushdown.js");
+const limitPushdown_ts_1 = require("./rules/limitPushdown.js");
+const sortFromIndex_ts_1 = require("./rules/sortFromIndex.js");
+const projectionPushdown_ts_1 = require("./rules/projectionPushdown.js");
+const validateScannable_ts_1 = require("./rules/validateScannable.js");
+const predicateNormalize_ts_1 = require("./rules/predicateNormalize.js");
+const planJoins_ts_1 = require("./rules/planJoins.js");
+function normalizePredicates(plan) {
+    switch (plan.kind) {
+        case 'Filter':
+            return {
+                ...plan,
+                predicate: (0, predicateNormalize_ts_1.normalizePredicate)(plan.predicate),
+                input: normalizePredicates(plan.input) ?? plan.input,
+            };
+        case 'Scan':
+            return plan.pushedFilter ? { ...plan, pushedFilter: (0, predicateNormalize_ts_1.normalizePredicate)(plan.pushedFilter) } : plan;
+        case 'Join':
+            return {
+                ...plan,
+                on: plan.on ? (0, predicateNormalize_ts_1.normalizePredicate)(plan.on) : plan.on,
+                left: normalizePredicates(plan.left) ?? plan.left,
+                right: normalizePredicates(plan.right) ?? plan.right,
+            };
+        default:
+            if ('input' in plan) {
+                return { ...plan, input: normalizePredicates(plan.input) ?? plan.input };
+            }
+            return plan;
+    }
+}
+function optimize(plan) {
+    const rules = [normalizePredicates, predicatePushdown_ts_1.predicatePushdown, sortFromIndex_ts_1.sortFromIndex, limitPushdown_ts_1.limitPushdown, projectionPushdown_ts_1.projectionPushdown, planJoins_ts_1.planJoins];
+    const optimized = (0, ruleEngine_ts_1.applyRules)(plan, rules);
+    (0, validateScannable_ts_1.validateScannable)(optimized);
+    return optimized;
+}
+//# sourceMappingURL=optimize.js.map

package/dist/sqlEngine/optimizer/optimize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize.js","sourceRoot":"","sources":["../../../sqlEngine/optimizer/optimize.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAqCH,4BAKC;AAvCD,mDAA6C;AAC7C,uEAAiE;AACjE,+DAAyD;AACzD,+DAAyD;AACzD,yEAAmE;AACnE,uEAAiE;AACjE,yEAAmE;AACnE,uDAAiD;AAEjD,SAAS,mBAAmB,CAAC,IAAiB;IAC7C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ;YACZ,OAAO;gBACN,GAAG,IAAI;gBACP,SAAS,EAAE,IAAA,0CAAkB,EAAC,IAAI,CAAC,SAAS,CAAC;gBAC7C,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK;aACpD,CAAC;QACH,KAAK,MAAM;YACV,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,IAAA,0CAAkB,EAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACpG,KAAK,MAAM;YACV,OAAO;gBACN,GAAG,IAAI;gBACP,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAA,0CAAkB,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;gBACnD,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;gBACjD,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK;aACpD,CAAC;QACH;YACC,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;gBACrB,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1E,CAAC;YACD,OAAO,IAAI,CAAC;IACd,CAAC;AACF,CAAC;AAED,SAAgB,QAAQ,CAAC,IAAiB;IACzC,MAAM,KAAK,GAAG,CAAC,mBAAmB,EAAE,wCAAiB,EAAE,gCAAa,EAAE,gCAAa,EAAE,0CAAkB,EAAE,wBAAS,CAAC,CAAC;IACpH,MAAM,SAAS,GAAG,IAAA,0BAAU,EAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,IAAA,wCAAiB,EAAC,SAAS,CAAC,CAAC;IAC7B,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/sqlEngine/optimizer/ruleEngine.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fixed-point rule engine. Phase 0 scaffold; rules under rules/ are added in
+ * phase 1+.
+ */
+import type { LogicalPlan } from '../logical/op.ts';
+export type Rule = (plan: LogicalPlan) => LogicalPlan | null;
+export declare function applyRules(plan: LogicalPlan, rules: Rule[]): LogicalPlan;

package/dist/sqlEngine/optimizer/ruleEngine.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Fixed-point rule engine. Phase 0 scaffold; rules under rules/ are added in
+ * phase 1+.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRules = applyRules;
+function applyRules(plan, rules) {
+    let current = plan;
+    let changed = true;
+    let iterations = 0;
+    const MAX_ITERATIONS = 32;
+    while (changed && iterations < MAX_ITERATIONS) {
+        changed = false;
+        iterations++;
+        for (const rule of rules) {
+            const next = rule(current);
+            if (next && next !== current) {
+                current = next;
+                changed = true;
+            }
+        }
+    }
+    return current;
+}
+//# sourceMappingURL=ruleEngine.js.map

package/dist/sqlEngine/optimizer/ruleEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleEngine.js","sourceRoot":"","sources":["../../../sqlEngine/optimizer/ruleEngine.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAMH,gCAiBC;AAjBD,SAAgB,UAAU,CAAC,IAAiB,EAAE,KAAa;IAC1D,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,cAAc,GAAG,EAAE,CAAC;IAC1B,OAAO,OAAO,IAAI,UAAU,GAAG,cAAc,EAAE,CAAC;QAC/C,OAAO,GAAG,KAAK,CAAC;QAChB,UAAU,EAAE,CAAC;QACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,IAAI,IAAI,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC9B,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,GAAG,IAAI,CAAC;YAChB,CAAC;QACF,CAAC;IACF,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC"}

package/dist/sqlEngine/optimizer/rules/limitPushdown.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rule R5: limit pushdown.
+ *
+ * If a Limit sits directly on top of a Scan (with optional Project/Sort that
+ * preserve cardinality through-pushdown), push the limit/offset into the
+ * Scan so Table.search returns only what we need.
+ *
+ * For phase 1 we push through Project unconditionally (a plain projection
+ * preserves cardinality) and through Sort only when the Sort itself is
+ * pushed into the scan (sortFromIndex rule has done that work).
+ *
+ * A limit is pushed into a Scan only when the scan carries no residual: if
+ * part of the WHERE lowers to a post-scan PhysicalFilter (whereToConditions
+ * residual, or an explicit residualFilter), Table.search would cap rows
+ * *before* that filter runs and silently under-fetch. In that case the Limit
+ * node is left above the residual filter.
+ */
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function limitPushdown(plan: LogicalPlan): LogicalPlan | null;

package/dist/sqlEngine/optimizer/rules/limitPushdown.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Rule R5: limit pushdown.
+ *
+ * If a Limit sits directly on top of a Scan (with optional Project/Sort that
+ * preserve cardinality through-pushdown), push the limit/offset into the
+ * Scan so Table.search returns only what we need.
+ *
+ * For phase 1 we push through Project unconditionally (a plain projection
+ * preserves cardinality) and through Sort only when the Sort itself is
+ * pushed into the scan (sortFromIndex rule has done that work).
+ *
+ * A limit is pushed into a Scan only when the scan carries no residual: if
+ * part of the WHERE lowers to a post-scan PhysicalFilter (whereToConditions
+ * residual, or an explicit residualFilter), Table.search would cap rows
+ * *before* that filter runs and silently under-fetch. In that case the Limit
+ * node is left above the residual filter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.limitPushdown = limitPushdown;
+const whereToConditions_ts_1 = require("../whereToConditions.js");
+function limitPushdown(plan) {
+    return rewrite(plan);
+}
+function scanHasResidual(scan) {
+    if (scan.residualFilter)
+        return true;
+    return (0, whereToConditions_ts_1.whereToConditions)(scan.pushedFilter, scan.boundTable?.attributes).residual !== undefined;
+}
+function rewrite(plan) {
+    switch (plan.kind) {
+        case 'Limit': {
+            const child = rewrite(plan.input);
+            if (child.kind === 'Scan' && !child.pushedLimit && !scanHasResidual(child)) {
+                return { ...child, pushedLimit: { limit: plan.limit, offset: plan.offset } };
+            }
+            if (child.kind === 'Project') {
+                const sub = rewrite({ ...plan, input: child.input });
+                return { ...child, input: sub };
+            }
+            return { ...plan, input: child };
+        }
+        case 'Project':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Sort':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Filter':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Distinct':
+            return { ...plan, input: rewrite(plan.input) };
+        default:
+            return plan;
+    }
+}
+//# sourceMappingURL=limitPushdown.js.map

package/dist/sqlEngine/optimizer/rules/limitPushdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitPushdown.js","sourceRoot":"","sources":["../../../../sqlEngine/optimizer/rules/limitPushdown.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAKH,sCAEC;AAJD,kEAA4D;AAE5D,SAAgB,aAAa,CAAC,IAAiB;IAC9C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,eAAe,CAAC,IAAiB;IACzC,IAAI,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,IAAA,wCAAiB,EAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC;AACjG,CAAC;AAED,SAAS,OAAO,CAAC,IAAiB;IACjC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,OAAO,CAAC,CAAC,CAAC;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5E,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAC9E,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAgB,CAAC;gBACpE,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;YACjC,CAAC;YACD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QACD,KAAK,SAAS;YACb,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,MAAM;YACV,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,QAAQ;YACZ,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,UAAU;YACd,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD;YACC,OAAO,IAAI,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/sqlEngine/optimizer/rules/planJoins.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Join-strategy rule.
+ *
+ * Sets `LogicalJoin.strategy` and, for index-nested-loop joins, marks the inner
+ * scan with `joinProbe` so validateScannable accepts it (it is served by an
+ * indexed equality probe, not a standalone full scan).
+ *
+ * Strategy choice:
+ *   - `indexNL`    — equi-join whose inner join key is an indexed column. The
+ *                    inner table is probed once per outer row; no full scan.
+ *   - `hash`       — equi-join without an indexed inner key. Reads the whole
+ *                    inner side (allowed only if the inner scan is otherwise
+ *                    index-served by its own WHERE, or allowFullScan is on).
+ *   - `nestedLoop` — CROSS joins and non-equi ON predicates.
+ *
+ * (`relationship` — the declared-relationship fast path — is a later addition.)
+ */
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function planJoins(plan: LogicalPlan): LogicalPlan | null;

package/dist/sqlEngine/optimizer/rules/planJoins.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Join-strategy rule.
+ *
+ * Sets `LogicalJoin.strategy` and, for index-nested-loop joins, marks the inner
+ * scan with `joinProbe` so validateScannable accepts it (it is served by an
+ * indexed equality probe, not a standalone full scan).
+ *
+ * Strategy choice:
+ *   - `indexNL`    — equi-join whose inner join key is an indexed column. The
+ *                    inner table is probed once per outer row; no full scan.
+ *   - `hash`       — equi-join without an indexed inner key. Reads the whole
+ *                    inner side (allowed only if the inner scan is otherwise
+ *                    index-served by its own WHERE, or allowFullScan is on).
+ *   - `nestedLoop` — CROSS joins and non-equi ON predicates.
+ *
+ * (`relationship` — the declared-relationship fast path — is a later addition.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planJoins = planJoins;
+const joinAnalysis_ts_1 = require("../joinAnalysis.js");
+function planJoins(plan) {
+    let mutated = false;
+    function walk(node) {
+        switch (node.kind) {
+            case 'Join': {
+                const left = walk(node.left);
+                const right = walk(node.right);
+                const next = { ...node, left, right };
+                if (!next.strategy) {
+                    assignStrategy(next);
+                    mutated = true;
+                }
+                return next;
+            }
+            default:
+                if ('input' in node) {
+                    const input = walk(node.input);
+                    return input === node.input ? node : { ...node, input };
+                }
+                return node;
+        }
+    }
+    const result = walk(plan);
+    return mutated ? result : null;
+}
+function assignStrategy(join) {
+    const analysis = (0, joinAnalysis_ts_1.analyzeJoin)(join);
+    if (!analysis || analysis.equiPairs.length === 0) {
+        join.strategy = 'nestedLoop';
+        return;
+    }
+    const probe = (0, joinAnalysis_ts_1.pickIndexedProbe)(analysis);
+    if (probe) {
+        join.strategy = 'indexNL';
+        analysis.rightScan.joinProbe = { keyAttribute: probe.attribute };
+    }
+    else {
+        join.strategy = 'hash';
+    }
+}
+//# sourceMappingURL=planJoins.js.map

package/dist/sqlEngine/optimizer/rules/planJoins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planJoins.js","sourceRoot":"","sources":["../../../../sqlEngine/optimizer/rules/planJoins.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAKH,8BA0BC;AA5BD,wDAAmE;AAEnE,SAAgB,SAAS,CAAC,IAAiB;IAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,SAAS,IAAI,CAAC,IAAiB;QAC9B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,CAAC,CAAC;gBACb,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC/B,MAAM,IAAI,GAAgB,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;gBACnD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACpB,cAAc,CAAC,IAAI,CAAC,CAAC;oBACrB,OAAO,GAAG,IAAI,CAAC;gBAChB,CAAC;gBACD,OAAO,IAAI,CAAC;YACb,CAAC;YACD;gBACC,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;oBACrB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBAC/B,OAAO,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC;gBACzD,CAAC;gBACD,OAAO,IAAI,CAAC;QACd,CAAC;IACF,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAChC,CAAC;AAED,SAAS,cAAc,CAAC,IAAiB;IACxC,MAAM,QAAQ,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC;QAC7B,OAAO;IACR,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,kCAAgB,EAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,SAAS,CAAC,SAAS,GAAG,EAAE,YAAY,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;IAClE,CAAC;SAAM,CAAC;QACP,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;IACxB,CAAC;AACF,CAAC"}

package/dist/sqlEngine/optimizer/rules/predicateNormalize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Rule R3: predicate normalization.
+ *
+ * Maps AlaSQL operator forms to a canonical shape ahead of pushdown:
+ *   - LIKE 'foo%'   ->  starts_with(foo)
+ *   - LIKE '%foo'   ->  ends_with(foo)
+ *   - LIKE '%foo%'  ->  contains(foo)
+ *   - BETWEEN a AND b -> binop chain (col >= a AND col <= b)  with semantic
+ *                       hint kept via marker for the pushdown rule
+ *   - NOT (a > b)   ->  a <= b (NULL semantics preserved by leaving NOT in
+ *                       place when the operand is anything other than a
+ *                       comparable binop on a single column ref)
+ *   - IS NULL / IS NOT NULL: left as-is (rule output for downstream).
+ *
+ * No change-of-meaning rewrites at this stage; the rule is conservative.
+ */
+import type { ExprNode } from '../../parser/ast.ts';
+export declare function normalizePredicate(expr: ExprNode): ExprNode;