@quereus/quereus 0.1.0

package/src/planner/stats/basic-estimates.ts

@@ -0,0 +1,107 @@
+/**
+ * Basic row and cost estimation utilities for plan nodes
+ * Used when more sophisticated statistics are not available
+ */
+
+import type { RelationalPlanNode } from '../nodes/plan-node.js';
+import type { OptimizerTuning } from '../optimizer-tuning.js';
+
+/**
+ * Basic row estimation heuristics
+ */
+export class BasicRowEstimator {
+	constructor(private readonly tuning: OptimizerTuning) {}
+
+	/**
+	 * Estimate rows for a filter operation
+	 * Default assumes 30% selectivity for most predicates
+	 */
+	estimateFilter(sourceRows: number): number {
+		return Math.max(1, Math.floor(sourceRows * 0.3));
+	}
+
+	/**
+	 * Estimate rows for a join operation
+	 */
+	estimateJoin(leftRows: number, rightRows: number, joinType: string): number {
+		switch (joinType.toLowerCase()) {
+			case 'inner':
+				// Inner join: assume moderate correlation
+				return Math.max(1, Math.floor(leftRows * rightRows * 0.1));
+			case 'left':
+			case 'left outer':
+				// Left join: at least as many as left side
+				return Math.max(leftRows, Math.floor(leftRows * rightRows * 0.1));
+			case 'right':
+			case 'right outer':
+				// Right join: at least as many as right side
+				return Math.max(rightRows, Math.floor(leftRows * rightRows * 0.1));
+			case 'full':
+			case 'full outer':
+				// Full outer join: sum minus overlap
+				return leftRows + rightRows - Math.floor(leftRows * rightRows * 0.1);
+			case 'cross':
+				// Cross join: cartesian product
+				return leftRows * rightRows;
+			default:
+				return Math.max(leftRows, rightRows);
+		}
+	}
+
+	/**
+	 * Estimate rows for aggregation
+	 */
+	estimateAggregate(sourceRows: number, groupByCount: number): number {
+		if (groupByCount === 0) {
+			return 1; // Single aggregate row
+		}
+		// Assume reasonable grouping factor
+		const groupingFactor = Math.min(0.8, Math.max(0.1, groupByCount * 0.2));
+		return Math.max(1, Math.floor(sourceRows * groupingFactor));
+	}
+
+	/**
+	 * Estimate rows for distinct operation
+	 */
+	estimateDistinct(sourceRows: number): number {
+		// Assume moderate duplication - 70% unique rows
+		return Math.max(1, Math.floor(sourceRows * 0.7));
+	}
+
+	/**
+	 * Estimate rows for limit operation
+	 */
+	estimateLimit(sourceRows: number, limit: number, offset: number = 0): number {
+		return Math.min(sourceRows, Math.max(0, limit - offset));
+	}
+
+	/**
+	 * Get default row estimate when no information is available
+	 */
+	getDefaultEstimate(): number {
+		return this.tuning.defaultRowEstimate;
+	}
+}
+
+/**
+ * Helper to safely get row estimate from a relational node
+ */
+export function getRowEstimate(node: RelationalPlanNode, tuning: OptimizerTuning): number {
+	return node.estimatedRows ?? tuning.defaultRowEstimate;
+}
+
+/**
+ * Helper to set row estimate on a node if not already set
+ */
+export function ensureRowEstimate(node: RelationalPlanNode, estimate: number): void {
+	if (node.estimatedRows === undefined) {
+		// Use Object.defineProperty to set a non-enumerable property
+		// This maintains the immutability principle while adding metadata
+		Object.defineProperty(node, 'estimatedRows', {
+			value: estimate,
+			writable: false,
+			enumerable: true,
+			configurable: false
+		});
+	}
+}

package/src/planner/stats/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Statistics provider abstraction for the Quereus optimizer
+ * Provides cardinality estimates and selectivity information for cost-based optimization
+ */
+
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import type { TableSchema } from '../../schema/table.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('optimizer:stats');
+
+/**
+ * Statistics provider interface for optimizer
+ */
+export interface StatsProvider {
+	/**
+	 * Get estimated row count for a base table
+	 * @param table Table schema
+	 * @returns Estimated row count, or undefined if unknown
+	 */
+	tableRows(table: TableSchema): number | undefined;
+
+	/**
+	 * Get selectivity estimate for a predicate on a table
+	 * @param table Table schema
+	 * @param predicate Predicate expression
+	 * @returns Selectivity factor (0.0 to 1.0), or undefined if unknown
+	 */
+	selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
+
+	/**
+	 * Get join selectivity estimate
+	 * @param leftTable Left table schema
+	 * @param rightTable Right table schema
+	 * @param joinCondition Join condition
+	 * @returns Join selectivity factor, or undefined if unknown
+	 */
+	joinSelectivity?(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined;
+
+	/**
+	 * Get number of distinct values for a column
+	 * @param table Table schema
+	 * @param columnName Column name
+	 * @returns Estimated distinct values, or undefined if unknown
+	 */
+	distinctValues?(table: TableSchema, columnName: string): number | undefined;
+
+	/**
+	 * Get index selectivity information
+	 * @param table Table schema
+	 * @param indexName Index name (if applicable)
+	 * @param predicate Predicate expression
+	 * @returns Index selectivity factor, or undefined if unknown
+	 */
+	indexSelectivity?(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
+}
+
+/**
+ * Naive statistics provider using simple heuristics
+ * Used as fallback when no better statistics are available
+ */
+export class NaiveStatsProvider implements StatsProvider {
+	constructor(
+		private readonly defaultTableRows: number = 1000,
+		private readonly defaultSelectivity: number = 0.3
+	) {
+		log('Created naive stats provider (defaultRows: %d, defaultSelectivity: %f)',
+			defaultTableRows, defaultSelectivity);
+	}
+
+	tableRows(table: TableSchema): number | undefined {
+		// Use table's estimated rows if available, otherwise use default
+		const estimate = table.estimatedRows ?? this.defaultTableRows;
+		log('Table %s estimated rows: %d (source: %s)',
+			table.name, estimate, table.estimatedRows ? 'schema' : 'default');
+		return estimate;
+	}
+
+	selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined {
+		// Simple heuristics based on predicate type
+		const selectivity = this.estimatePredicateSelectivity(predicate);
+		log('Predicate selectivity for %s: %f', predicate.nodeType, selectivity);
+		return selectivity;
+	}
+
+	joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, _joinCondition: ScalarPlanNode): number | undefined {
+		// Default join selectivity based on table sizes
+		const leftRows = this.tableRows(leftTable) ?? this.defaultTableRows;
+		const rightRows = this.tableRows(rightTable) ?? this.defaultTableRows;
+
+		// Simple heuristic: smaller table determines selectivity
+		const selectivity = 1.0 / Math.max(leftRows, rightRows, 10);
+		log('Join selectivity between %s and %s: %f', leftTable.name, rightTable.name, selectivity);
+		return Math.min(0.5, selectivity);
+	}
+
+	distinctValues(table: TableSchema, columnName: string): number | undefined {
+		const totalRows = this.tableRows(table);
+		if (!totalRows) return undefined;
+
+		// Heuristic: assume moderate cardinality (50% distinct values)
+		const distinct = Math.max(1, Math.floor(totalRows * 0.5));
+		log('Distinct values for %s.%s: %d', table.name, columnName, distinct);
+		return distinct;
+	}
+
+	indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined {
+		// Index selectivity is generally better than table scan
+		const baseSelecivity = this.selectivity(table, predicate) ?? this.defaultSelectivity;
+		const indexSelectivity = baseSelecivity * 0.8; // 20% improvement with index
+		log('Index %s selectivity: %f (base: %f)', indexName, indexSelectivity, baseSelecivity);
+		return indexSelectivity;
+	}
+
+	private estimatePredicateSelectivity(predicate: ScalarPlanNode): number {
+		// Simple heuristics based on node type
+		switch (predicate.nodeType) {
+			case 'BinaryOp':
+				// More selective for equality, less for ranges
+				return 0.1; // Equality-like operations
+			case 'In':
+				return 0.2; // IN clauses
+			case 'Between':
+				return 0.25; // Range queries
+			case 'Like':
+				return 0.3; // Pattern matching
+			case 'IsNull':
+			case 'IsNotNull':
+				return 0.1; // NULL checks are usually selective
+			default:
+				return this.defaultSelectivity;
+		}
+	}
+}
+
+/**
+ * Statistics provider that delegates to virtual table modules
+ * Allows VTab modules to provide their own statistics
+ */
+export class VTabStatsProvider implements StatsProvider {
+	constructor(
+		private readonly fallback: StatsProvider = new NaiveStatsProvider()
+	) {
+		log('Created VTab stats provider with fallback');
+	}
+
+	tableRows(table: TableSchema): number | undefined {
+		// Try to get stats from VTab module if it supports it
+		if (table.vtabModule && typeof table.vtabModule === 'object' && 'getTableStats' in table.vtabModule) {
+			try {
+				const stats = (table.vtabModule as any).getTableStats?.(table);
+				if (stats?.rowCount !== undefined) {
+					log('Got row count from VTab module for %s: %d', table.name, stats.rowCount);
+					return stats.rowCount;
+				}
+			} catch (error) {
+				log('Error getting VTab stats for %s: %s', table.name, error);
+			}
+		}
+
+		// Fall back to default provider
+		return this.fallback.tableRows(table);
+	}
+
+	selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined {
+		// Try VTab module selectivity
+		if (table.vtabModule && typeof table.vtabModule === 'object' && 'getSelectivity' in table.vtabModule) {
+			try {
+				const selectivity = (table.vtabModule as any).getSelectivity?.(table, predicate);
+				if (selectivity !== undefined) {
+					log('Got selectivity from VTab module for %s: %f', table.name, selectivity);
+					return selectivity;
+				}
+			} catch (error) {
+				log('Error getting VTab selectivity for %s: %s', table.name, error);
+			}
+		}
+
+		// Fall back to default provider
+		return this.fallback.selectivity(table, predicate);
+	}
+
+	joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined {
+		return this.fallback.joinSelectivity?.(leftTable, rightTable, joinCondition);
+	}
+
+	distinctValues(table: TableSchema, columnName: string): number | undefined {
+		return this.fallback.distinctValues?.(table, columnName);
+	}
+
+	indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined {
+		return this.fallback.indexSelectivity?.(table, indexName, predicate);
+	}
+}
+
+/**
+ * Default statistics provider instance
+ */
+export const defaultStatsProvider = new NaiveStatsProvider();
+
+/**
+ * VTab-aware statistics provider instance
+ */
+export const vtabStatsProvider = new VTabStatsProvider();
+
+/**
+ * Create a custom statistics provider
+ */
+export function createStatsProvider(
+	tableRowsMap?: Map<string, number>,
+	selectivityMap?: Map<string, number>
+): StatsProvider {
+	return new class implements StatsProvider {
+		tableRows(table: TableSchema): number | undefined {
+			return tableRowsMap?.get(table.name) ?? defaultStatsProvider.tableRows(table);
+		}
+
+		selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined {
+			const key = `${table.name}:${predicate.nodeType}`;
+			return selectivityMap?.get(key) ?? defaultStatsProvider.selectivity(table, predicate);
+		}
+	};
+}

package/src/planner/type-utils.ts

@@ -0,0 +1,95 @@
+import type { TableSchema } from '../schema/table.js';
+import type { ColumnSchema } from '../schema/column.js';
+import type { RelationType, ColumnDef, ScalarType, ColRef } from '../common/datatype.js';
+import { SqlDataType, StatusCode, type DeepReadonly, type SqlValue } from '../common/types.js'; // Import SqlValue and ensure SqlDataType is not type-only
+import type { AstNode } from '../parser/ast.js';
+import { QuereusError } from '../common/errors.js';
+// Note: getAffinity from '../schema/column.js' is used by the ColumnSchema type from table.js itself if that's what we use.
+// If tableSchema.columns are of type from '../schema/column.js', then their affinity is already SqlDataType.
+
+/**
+ * Converts a TableSchema (from src/schema/table.ts) to a RelationType (from src/common/datatype.ts).
+ * This is used by PlanNodes that source data directly from a base table.
+ */
+export function relationTypeFromTableSchema(tableSchema: TableSchema): RelationType {
+  const columnDefs: ColumnDef[] = tableSchema.columns.map((col: ColumnSchema) => {
+    return {
+      name: col.name,
+      type: {
+				typeClass: 'scalar',
+				affinity: col.affinity,
+				collationName: col.collation,
+				nullable: !col.notNull,
+				isReadOnly: false,
+			},
+      generated: col.generated,
+    };
+  });
+
+  // Populate keys from primaryKeyDefinition
+  const keys: ColRef[][] = [];
+  if (tableSchema.primaryKeyDefinition && tableSchema.primaryKeyDefinition.length > 0) {
+    const primaryKey: ColRef[] = tableSchema.primaryKeyDefinition.map(pkCol => ({
+      index: pkCol.index,
+      desc: pkCol.desc,
+    }));
+    keys.push(primaryKey);
+  }
+
+  return {
+    typeClass: 'relation',
+    isReadOnly: !!(tableSchema.isView || tableSchema.isTemporary),
+    isSet: true, // Base tables are sets by definition (enforced by primary keys)
+    columns: columnDefs,
+    keys: keys,
+    // TODO: Populate rowConstraints from tableSchema if/when RelationType supports them
+    rowConstraints: [], // Placeholder
+  };
+}
+
+/**
+ * Creates a ScalarType for a given SqlValue, typically for parameters.
+ * @param value The SqlValue to determine the type for.
+ * @returns A ScalarType representing the inferred type of the value.
+ */
+export function getParameterScalarType(value: SqlValue): ScalarType {
+  let affinity: SqlDataType;
+  if (value === null) affinity = SqlDataType.NULL;
+  else if (typeof value === 'number') affinity = SqlDataType.REAL;
+  else if (typeof value === 'bigint') affinity = SqlDataType.INTEGER;
+  else if (typeof value === 'string') affinity = SqlDataType.TEXT;
+  else if (value instanceof Uint8Array) affinity = SqlDataType.BLOB;
+  else if (typeof value === 'boolean') affinity = SqlDataType.INTEGER; // Store booleans as INTEGER
+  else affinity = SqlDataType.BLOB; // Default for unknown types that might pass as SqlValue
+
+  return {
+    typeClass: 'scalar',
+    affinity: affinity,
+    nullable: true,	// No guarantees about the value, so it's nullable
+    isReadOnly: true, // Parameters are read-only within the query execution context
+  };
+}
+
+export function checkColumnsAssignable(source: DeepReadonly<ColumnDef[]>, target: DeepReadonly<ColumnDef[]>, astNode?: AstNode): void {
+	if (source.length !== target.length) {
+		throw new QuereusError(`Column count mismatch ${(astNode ? astNode.type + ' clause' : '')}.`, StatusCode.ERROR, undefined, astNode?.loc?.start.line, astNode?.loc?.start.column);
+	}
+}
+
+export function checkRelationsAssignable(source: RelationType, target: RelationType, astNode?: AstNode): void {
+	return checkColumnsAssignable(source.columns, target.columns, astNode);
+}
+
+export function columnSchemaToDef(colName: string, colDef: ColumnSchema): { name: string; type: { typeClass: "scalar"; affinity: SqlDataType; collationName: string; nullable: boolean; isReadOnly: false; }; generated: boolean; } {
+	return {
+		name: colName,
+		type: {
+			typeClass: 'scalar',
+			affinity: colDef.affinity,
+			collationName: colDef.collation,
+			nullable: !colDef.notNull,
+			isReadOnly: false,
+		},
+		generated: colDef.generated,
+	};
+}