@quereus/quereus 0.17.0 → 0.18.0

package/dist/src/planner/stats/analyze.js

@@ -0,0 +1,114 @@
+/**
+ * Statistics collection via table scanning.
+ * Used as fallback when a VTab module doesn't implement getStatistics().
+ */
+import { buildHistogram } from './histogram.js';
+import { compareSqlValues } from '../../util/comparison.js';
+import { createLogger } from '../../common/logger.js';
+const log = createLogger('stats:analyze');
+/**
+ * Collect statistics by scanning all rows from a VTable instance.
+ * Computes row count, per-column distinct counts, null counts, min/max, and optional histograms.
+ *
+ * @param vtab Connected VirtualTable instance with query() support
+ * @param tableSchema Schema describing the table structure
+ * @returns Collected TableStatistics, or undefined if scanning is not supported
+ */
+export async function collectStatisticsFromScan(vtab, tableSchema) {
+    if (typeof vtab.query !== 'function') {
+        log('Table %s does not support query(), skipping scan-based analysis', tableSchema.name);
+        return undefined;
+    }
+    const colCount = tableSchema.columns.length;
+    const distinctSets = Array.from({ length: colCount }, () => new Set());
+    const nullCounts = new Array(colCount).fill(0);
+    const minValues = new Array(colCount).fill(undefined);
+    const maxValues = new Array(colCount).fill(undefined);
+    const sampleValues = Array.from({ length: colCount }, () => []);
+    let rowCount = 0;
+    const maxSample = 1000;
+    // Full scan with a minimal filter that returns all rows
+    const filterInfo = {
+        idxNum: 0,
+        idxStr: null,
+        constraints: [],
+        args: [],
+        indexInfoOutput: {
+            nConstraint: 0,
+            aConstraint: [],
+            nOrderBy: 0,
+            aOrderBy: [],
+            colUsed: 0n,
+            aConstraintUsage: [],
+            idxNum: 0,
+            idxStr: null,
+            orderByConsumed: false,
+            estimatedCost: Infinity,
+            estimatedRows: BigInt(Number.MAX_SAFE_INTEGER),
+            idxFlags: 0,
+        },
+    };
+    try {
+        for await (const row of vtab.query(filterInfo)) {
+            rowCount++;
+            for (let i = 0; i < colCount && i < row.length; i++) {
+                const val = row[i];
+                if (val === null || val === undefined) {
+                    nullCounts[i]++;
+                }
+                else {
+                    distinctSets[i].add(String(val));
+                    // Track min/max
+                    if (minValues[i] === undefined || compareSqlValues(val, minValues[i]) < 0) {
+                        minValues[i] = val;
+                    }
+                    if (maxValues[i] === undefined || compareSqlValues(val, maxValues[i]) > 0) {
+                        maxValues[i] = val;
+                    }
+                    // Collect sample values for histograms (reservoir sampling simplified)
+                    if (sampleValues[i].length < maxSample) {
+                        sampleValues[i].push(val);
+                    }
+                    else {
+                        // Reservoir sampling: replace with decreasing probability
+                        const j = Math.floor(Math.random() * rowCount);
+                        if (j < maxSample) {
+                            sampleValues[i][j] = val;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch (e) {
+        log('Error scanning table %s: %s', tableSchema.name, e);
+        return undefined;
+    }
+    // Build column statistics
+    const columnStats = new Map();
+    for (let i = 0; i < colCount; i++) {
+        const col = tableSchema.columns[i];
+        const colName = col.name.toLowerCase();
+        const sortedSample = sampleValues[i].sort((a, b) => compareSqlValues(a, b));
+        const stats = {
+            distinctCount: distinctSets[i].size,
+            nullCount: nullCounts[i],
+            minValue: minValues[i] ?? undefined,
+            maxValue: maxValues[i] ?? undefined,
+        };
+        // Build histogram for columns with enough distinct values
+        if (sortedSample.length > 10) {
+            const hist = buildHistogram(sortedSample, Math.min(100, Math.ceil(sortedSample.length / 10)));
+            if (hist) {
+                stats.histogram = hist;
+            }
+        }
+        columnStats.set(colName, stats);
+    }
+    return {
+        rowCount,
+        columnStats,
+        lastAnalyzed: Date.now(),
+    };
+}
+//# sourceMappingURL=analyze.js.map

package/dist/src/planner/stats/analyze.js.map

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

package/dist/src/planner/stats/catalog-stats.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Catalog-backed statistics types and provider
+ *
+ * Reads real statistics from TableSchema.statistics (populated by ANALYZE or VTab)
+ * and falls back to NaiveStatsProvider heuristics when unavailable.
+ */
+import type { SqlValue } from '../../common/types.js';
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import type { TableSchema } from '../../schema/table.js';
+import type { StatsProvider } from './index.js';
+import { NaiveStatsProvider } from './index.js';
+/**
+ * An equi-height histogram bucket.
+ * Buckets are cumulative: `cumulativeCount` is the total rows up to and including this bucket.
+ */
+export interface HistogramBucket {
+    /** Upper bound of this bucket (inclusive) */
+    upperBound: SqlValue;
+    /** Cumulative row count up to and including this bucket */
+    cumulativeCount: number;
+    /** Estimated distinct values in this bucket */
+    distinctCount: number;
+}
+/**
+ * Equi-height histogram for a column's value distribution.
+ */
+export interface EquiHeightHistogram {
+    buckets: readonly HistogramBucket[];
+    /** Number of rows sampled to build this histogram */
+    sampleSize: number;
+}
+/**
+ * Statistics for a single column.
+ */
+export interface ColumnStatistics {
+    /** Estimated number of distinct non-null values */
+    distinctCount: number;
+    /** Count of NULL values */
+    nullCount: number;
+    /** Minimum value (for range estimation) */
+    minValue?: SqlValue;
+    /** Maximum value (for range estimation) */
+    maxValue?: SqlValue;
+    /** Optional histogram for fine-grained selectivity */
+    histogram?: EquiHeightHistogram;
+}
+/**
+ * Cached statistics for a table, populated by ANALYZE or VTab reporting.
+ */
+export interface TableStatistics {
+    /** Exact or estimated row count */
+    rowCount: number;
+    /** Per-column statistics keyed by lowercase column name */
+    columnStats: ReadonlyMap<string, ColumnStatistics>;
+    /** Epoch ms when statistics were last collected */
+    lastAnalyzed?: number;
+}
+/**
+ * Statistics provider that reads cached TableStatistics from the schema catalog.
+ * Falls back to a NaiveStatsProvider when real statistics are not available.
+ */
+export declare class CatalogStatsProvider implements StatsProvider {
+    private readonly fallback;
+    constructor(fallback?: NaiveStatsProvider);
+    tableRows(table: TableSchema): number | undefined;
+    selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
+    joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined;
+    /**
+     * Check if an equi-join column pair represents a FK→PK relationship.
+     * If so, return selectivity = 1/ndv_pk (each FK row matches at most one PK row).
+     */
+    private fkPkSelectivity;
+    private isFkColumn;
+    private getPkDistinct;
+    distinctValues(table: TableSchema, columnName: string): number | undefined;
+    indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
+    private getDistinct;
+    private estimatePredicateSelectivity;
+}
+//# sourceMappingURL=catalog-stats.d.ts.map

package/dist/src/planner/stats/catalog-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-stats.d.ts","sourceRoot":"","sources":["../../../../src/planner/stats/catalog-stats.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAQhD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,6CAA6C;IAC7C,UAAU,EAAE,QAAQ,CAAC;IACrB,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,sDAAsD;IACtD,SAAS,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACnD,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,QAAQ,CAAC,EAAE,kBAAkB;IAIzC,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IASjD,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAY9E,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAwBnH;;;OAGG;IACH,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,aAAa;IAMrB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM1E,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAStG,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,4BAA4B;CAgFpC"}

package/dist/src/planner/stats/catalog-stats.js

@@ -0,0 +1,248 @@
+/**
+ * Catalog-backed statistics types and provider
+ *
+ * Reads real statistics from TableSchema.statistics (populated by ANALYZE or VTab)
+ * and falls back to NaiveStatsProvider heuristics when unavailable.
+ */
+import { NaiveStatsProvider } from './index.js';
+import { createLogger } from '../../common/logger.js';
+import { selectivityFromHistogram } from './histogram.js';
+const log = createLogger('optimizer:stats:catalog');
+// ── CatalogStatsProvider ────────────────────────────────────────────────
+/**
+ * Statistics provider that reads cached TableStatistics from the schema catalog.
+ * Falls back to a NaiveStatsProvider when real statistics are not available.
+ */
+export class CatalogStatsProvider {
+    fallback;
+    constructor(fallback) {
+        this.fallback = fallback ?? new NaiveStatsProvider();
+    }
+    tableRows(table) {
+        const stats = table.statistics;
+        if (stats) {
+            log('Table %s: catalog rowCount=%d', table.name, stats.rowCount);
+            return stats.rowCount;
+        }
+        return this.fallback.tableRows(table);
+    }
+    selectivity(table, predicate) {
+        const stats = table.statistics;
+        if (!stats)
+            return this.fallback.selectivity(table, predicate);
+        const sel = this.estimatePredicateSelectivity(stats, predicate);
+        if (sel !== undefined) {
+            log('Predicate selectivity for %s on %s: %f (catalog)', predicate.nodeType, table.name, sel);
+            return sel;
+        }
+        return this.fallback.selectivity(table, predicate);
+    }
+    joinSelectivity(leftTable, rightTable, joinCondition) {
+        // For equi-joins, use 1/max(ndv_left, ndv_right) if we can extract columns
+        const colNames = extractEquiJoinColumns(joinCondition);
+        if (colNames) {
+            // Check FK→PK: if one side has an FK referencing the other's PK,
+            // use 1/ndv_pk for tighter selectivity
+            const fkSel = this.fkPkSelectivity(leftTable, rightTable, colNames.left, colNames.right);
+            if (fkSel !== undefined) {
+                log('Join selectivity %s⋈%s: %f (FK→PK)', leftTable.name, rightTable.name, fkSel);
+                return fkSel;
+            }
+            const leftNdv = this.getDistinct(leftTable, colNames.left);
+            const rightNdv = this.getDistinct(rightTable, colNames.right);
+            if (leftNdv !== undefined && rightNdv !== undefined) {
+                const sel = 1 / Math.max(leftNdv, rightNdv, 1);
+                log('Join selectivity %s⋈%s: %f (ndv left=%d, right=%d)', leftTable.name, rightTable.name, sel, leftNdv, rightNdv);
+                return sel;
+            }
+        }
+        return this.fallback.joinSelectivity?.(leftTable, rightTable, joinCondition);
+    }
+    /**
+     * Check if an equi-join column pair represents a FK→PK relationship.
+     * If so, return selectivity = 1/ndv_pk (each FK row matches at most one PK row).
+     */
+    fkPkSelectivity(leftTable, rightTable, leftColName, rightColName) {
+        // Check: left FK → right PK
+        if (this.isFkColumn(leftTable, leftColName, rightTable)) {
+            const pkNdv = this.getPkDistinct(rightTable);
+            if (pkNdv !== undefined)
+                return 1 / Math.max(pkNdv, 1);
+        }
+        // Check: right FK → left PK
+        if (this.isFkColumn(rightTable, rightColName, leftTable)) {
+            const pkNdv = this.getPkDistinct(leftTable);
+            if (pkNdv !== undefined)
+                return 1 / Math.max(pkNdv, 1);
+        }
+        return undefined;
+    }
+    isFkColumn(table, colName, referencedTable) {
+        if (!table.foreignKeys)
+            return false;
+        const colIdx = table.columnIndexMap.get(colName.toLowerCase());
+        if (colIdx === undefined)
+            return false;
+        return table.foreignKeys.some(fk => fk.referencedTable.toLowerCase() === referencedTable.name.toLowerCase() &&
+            fk.columns.includes(colIdx));
+    }
+    getPkDistinct(table) {
+        if (table.primaryKeyDefinition.length !== 1)
+            return undefined;
+        const pkCol = table.columns[table.primaryKeyDefinition[0].index];
+        return this.getDistinct(table, pkCol.name);
+    }
+    distinctValues(table, columnName) {
+        const ndv = this.getDistinct(table, columnName);
+        if (ndv !== undefined)
+            return ndv;
+        return this.fallback.distinctValues?.(table, columnName);
+    }
+    indexSelectivity(table, indexName, predicate) {
+        // Delegate to base selectivity — real column stats already improve this
+        const sel = this.selectivity(table, predicate);
+        if (sel !== undefined)
+            return sel;
+        return this.fallback.indexSelectivity?.(table, indexName, predicate);
+    }
+    // ── Internal helpers ──────────────────────────────────────────────
+    getDistinct(table, columnName) {
+        const colStats = table.statistics?.columnStats.get(columnName.toLowerCase());
+        return colStats?.distinctCount;
+    }
+    estimatePredicateSelectivity(stats, predicate) {
+        if (stats.rowCount === 0)
+            return 0;
+        // Try to extract column reference from the predicate for column-level estimation
+        const colInfo = extractColumnFromPredicate(predicate);
+        if (!colInfo)
+            return undefined;
+        const colStats = stats.columnStats.get(colInfo.columnName.toLowerCase());
+        if (!colStats)
+            return undefined;
+        const { rowCount } = stats;
+        switch (predicate.nodeType) {
+            case 'BinaryOp': {
+                const op = predicate.op;
+                if (!op)
+                    return undefined;
+                // Equality: 1/ndv
+                if (op === '=' || op === '==') {
+                    return 1 / Math.max(colStats.distinctCount, 1);
+                }
+                // Not-equal: 1 - 1/ndv
+                if (op === '!=' || op === '<>') {
+                    return 1 - (1 / Math.max(colStats.distinctCount, 1));
+                }
+                // Range operators: use histogram if available, else uniform assumption
+                if (op === '>' || op === '>=' || op === '<' || op === '<=') {
+                    if (colStats.histogram) {
+                        const value = extractConstantValue(predicate);
+                        if (value !== undefined) {
+                            return selectivityFromHistogram(colStats.histogram, op, value, rowCount);
+                        }
+                    }
+                    // Uniform assumption: 1/3 for open-ended range
+                    return 1 / 3;
+                }
+                return undefined;
+            }
+            case 'IsNull':
+                return colStats.nullCount / Math.max(rowCount, 1);
+            case 'IsNotNull':
+                return 1 - (colStats.nullCount / Math.max(rowCount, 1));
+            case 'In': {
+                // IN list: listSize / ndv
+                const listSize = extractInListSize(predicate);
+                if (listSize !== undefined) {
+                    return Math.min(1.0, listSize / Math.max(colStats.distinctCount, 1));
+                }
+                return undefined;
+            }
+            case 'Between': {
+                if (colStats.histogram) {
+                    const bounds = extractBetweenBounds(predicate);
+                    if (bounds) {
+                        const lowSel = selectivityFromHistogram(colStats.histogram, '>=', bounds.low, rowCount);
+                        const highSel = selectivityFromHistogram(colStats.histogram, '<=', bounds.high, rowCount);
+                        if (lowSel !== undefined && highSel !== undefined) {
+                            return Math.max(0, lowSel + highSel - 1);
+                        }
+                    }
+                }
+                return 1 / 4; // heuristic fallback
+            }
+            case 'Like':
+                return 1 / 3; // heuristic: pattern matching is moderately selective
+            default:
+                return undefined;
+        }
+    }
+}
+// ── Predicate introspection helpers ─────────────────────────────────────
+// These extract structural info from plan nodes without importing concrete node types.
+// They use duck typing consistent with the characteristics-based optimizer conventions.
+function extractColumnFromPredicate(predicate) {
+    // BinaryOp, In, Between, IsNull, Like all typically have a column child
+    const children = predicate.getChildren();
+    for (const child of children) {
+        if (child.nodeType === 'ColumnReference') {
+            const colRef = child;
+            const name = colRef.columnName ?? colRef.name;
+            if (name)
+                return { columnName: name };
+        }
+    }
+    return undefined;
+}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function extractConstantValue(predicate) {
+    const children = predicate.getChildren();
+    for (const child of children) {
+        if (child.nodeType === 'Literal') {
+            return child.value;
+        }
+    }
+    return undefined;
+}
+function extractInListSize(predicate) {
+    const node = predicate;
+    if (Array.isArray(node.values))
+        return node.values.length;
+    // Some IN nodes store the list in children after the first (column) child
+    const children = predicate.getChildren();
+    if (children.length > 1)
+        return children.length - 1;
+    return undefined;
+}
+function extractBetweenBounds(predicate) {
+    const node = predicate;
+    if (node.low !== undefined && node.high !== undefined) {
+        const lowVal = node.low.nodeType === 'Literal' ? node.low.value : undefined;
+        const highVal = node.high.nodeType === 'Literal' ? node.high.value : undefined;
+        if (lowVal !== undefined && highVal !== undefined) {
+            return { low: lowVal, high: highVal };
+        }
+    }
+    return undefined;
+}
+function extractEquiJoinColumns(condition) {
+    if (condition.nodeType !== 'BinaryOp')
+        return undefined;
+    const op = condition.op;
+    if (op !== '=' && op !== '==')
+        return undefined;
+    const children = condition.getChildren();
+    if (children.length !== 2)
+        return undefined;
+    const left = children[0];
+    const right = children[1];
+    if (left.nodeType !== 'ColumnReference' || right.nodeType !== 'ColumnReference')
+        return undefined;
+    const leftName = left.columnName ?? left.name;
+    const rightName = right.columnName ?? right.name;
+    if (!leftName || !rightName)
+        return undefined;
+    return { left: leftName, right: rightName };
+}
+//# sourceMappingURL=catalog-stats.js.map

package/dist/src/planner/stats/catalog-stats.js.map

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

package/dist/src/planner/stats/histogram.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Equi-height histogram utilities for selectivity estimation
+ */
+import type { SqlValue } from '../../common/types.js';
+import type { EquiHeightHistogram } from './catalog-stats.js';
+/**
+ * Estimate selectivity for a range predicate using a histogram.
+ *
+ * @param histogram The column's equi-height histogram
+ * @param op Comparison operator: '>', '>=', '<', '<=', '='
+ * @param value The constant value being compared
+ * @param totalRows Total row count for the table
+ * @returns Selectivity in [0, 1], or undefined if estimation fails
+ */
+export declare function selectivityFromHistogram(histogram: EquiHeightHistogram, op: string, value: SqlValue, totalRows: number): number | undefined;
+/**
+ * Build an equi-height histogram from sorted values.
+ *
+ * @param sortedValues Sorted array of non-null column values
+ * @param numBuckets Target number of buckets
+ * @returns Histogram, or undefined if too few values
+ */
+export declare function buildHistogram(sortedValues: SqlValue[], numBuckets: number): EquiHeightHistogram | undefined;
+//# sourceMappingURL=histogram.d.ts.map

package/dist/src/planner/stats/histogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../../../src/planner/stats/histogram.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,oBAAoB,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,mBAAmB,EAC9B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAgDpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,YAAY,EAAE,QAAQ,EAAE,EACxB,UAAU,EAAE,MAAM,GAChB,mBAAmB,GAAG,SAAS,CA2BjC"}

package/dist/src/planner/stats/histogram.js

@@ -0,0 +1,142 @@
+/**
+ * Equi-height histogram utilities for selectivity estimation
+ */
+import { compareSqlValues } from '../../util/comparison.js';
+/**
+ * Estimate selectivity for a range predicate using a histogram.
+ *
+ * @param histogram The column's equi-height histogram
+ * @param op Comparison operator: '>', '>=', '<', '<=', '='
+ * @param value The constant value being compared
+ * @param totalRows Total row count for the table
+ * @returns Selectivity in [0, 1], or undefined if estimation fails
+ */
+export function selectivityFromHistogram(histogram, op, value, totalRows) {
+    const { buckets } = histogram;
+    if (buckets.length === 0 || totalRows === 0)
+        return undefined;
+    // Find the bucket containing `value` via binary search on upperBound
+    const idx = findBucket(buckets, value);
+    const total = buckets[buckets.length - 1].cumulativeCount;
+    if (total === 0)
+        return 0;
+    switch (op) {
+        case '=':
+        case '==': {
+            // Point query: estimate 1/distinctCount within the containing bucket
+            if (idx < 0 || idx >= buckets.length)
+                return 0;
+            const bucket = buckets[idx];
+            return Math.min(1, 1 / Math.max(bucket.distinctCount, 1));
+        }
+        case '<': {
+            if (idx < 0)
+                return 0;
+            if (idx >= buckets.length)
+                return 1;
+            return interpolateCumulative(buckets, idx, value) / total;
+        }
+        case '<=': {
+            if (idx < 0)
+                return 0;
+            if (idx >= buckets.length)
+                return 1;
+            // Include the value itself
+            const cum = interpolateCumulative(buckets, idx, value);
+            return Math.min(1, cum / total);
+        }
+        case '>': {
+            if (idx >= buckets.length)
+                return 0;
+            if (idx < 0)
+                return 1;
+            return 1 - (interpolateCumulative(buckets, idx, value) / total);
+        }
+        case '>=': {
+            if (idx >= buckets.length)
+                return 0;
+            if (idx < 0)
+                return 1;
+            return 1 - (interpolateCumulative(buckets, idx, value) / total) +
+                (1 / Math.max(buckets[idx]?.distinctCount ?? 1, 1) / total);
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Build an equi-height histogram from sorted values.
+ *
+ * @param sortedValues Sorted array of non-null column values
+ * @param numBuckets Target number of buckets
+ * @returns Histogram, or undefined if too few values
+ */
+export function buildHistogram(sortedValues, numBuckets) {
+    if (sortedValues.length === 0)
+        return undefined;
+    const n = sortedValues.length;
+    const actualBuckets = Math.min(numBuckets, n);
+    const bucketSize = n / actualBuckets;
+    const buckets = [];
+    for (let i = 0; i < actualBuckets; i++) {
+        const start = Math.floor(i * bucketSize);
+        const end = Math.floor((i + 1) * bucketSize);
+        const upperIdx = Math.min(end - 1, n - 1);
+        // Count distinct values within this bucket
+        const distinct = new Set();
+        for (let j = start; j <= upperIdx; j++) {
+            distinct.add(String(sortedValues[j]));
+        }
+        buckets.push({
+            upperBound: sortedValues[upperIdx],
+            cumulativeCount: end,
+            distinctCount: distinct.size
+        });
+    }
+    return { buckets, sampleSize: n };
+}
+// ── Internals ───────────────────────────────────────────────────────────
+/**
+ * Binary search for the bucket whose upperBound >= value.
+ * Returns the bucket index, or -1 if value < all bounds, or buckets.length if value > all bounds.
+ */
+function findBucket(buckets, value) {
+    let lo = 0;
+    let hi = buckets.length - 1;
+    // Value below first bucket
+    if (compareSqlValues(value, buckets[0].upperBound) < 0) {
+        // Could still be in the first bucket range
+        return 0;
+    }
+    // Value above last bucket
+    if (compareSqlValues(value, buckets[hi].upperBound) > 0) {
+        return buckets.length;
+    }
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (compareSqlValues(buckets[mid].upperBound, value) < 0) {
+            lo = mid + 1;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return lo;
+}
+/**
+ * Linear interpolation of cumulative count at a value within a bucket.
+ * Assumes uniform distribution within each bucket.
+ */
+function interpolateCumulative(buckets, idx, _value) {
+    if (idx < 0)
+        return 0;
+    if (idx >= buckets.length)
+        return buckets[buckets.length - 1].cumulativeCount;
+    const bucket = buckets[idx];
+    const prevCum = idx > 0 ? buckets[idx - 1].cumulativeCount : 0;
+    const bucketRows = bucket.cumulativeCount - prevCum;
+    // Without numeric distance computation (values may be non-numeric),
+    // assume the value is at the midpoint of the bucket
+    return prevCum + bucketRows / 2;
+}
+//# sourceMappingURL=histogram.js.map

package/dist/src/planner/stats/histogram.js.map

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

package/dist/src/planner/type-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../../../src/planner/type-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAU,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAA2B,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAIhD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,CAkClF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CASlE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAIpI;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAE5G;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,CAYlF"}
+{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../../../src/planner/type-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAU,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAIhD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,CAyClF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CASlE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAIpI;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAE5G;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,CAYlF"}