@quereus/quereus 0.1.0

package/src/planner/nodes/join-node.ts

@@ -0,0 +1,213 @@
+import { PlanNode } from './plan-node.js';
+import type { RelationalPlanNode, Attribute, BinaryRelationalNode, ScalarPlanNode } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import { Cached } from '../../util/cached.js';
+import { StatusCode } from '../../common/types.js';
+import { quereusError } from '../../common/errors.js';
+
+export type JoinType = 'inner' | 'left' | 'right' | 'full' | 'cross';
+
+/**
+ * Represents a logical JOIN operation between two relations.
+ * This is a logical node that will be converted to physical join algorithms during optimization.
+ */
+export class JoinNode extends PlanNode implements BinaryRelationalNode {
+	readonly nodeType = PlanNodeType.Join;
+	private attributesCache: Cached<Attribute[]>;
+
+	constructor(
+		scope: Scope,
+		public readonly left: RelationalPlanNode,
+		public readonly right: RelationalPlanNode,
+		public readonly joinType: JoinType,
+		public readonly condition?: ScalarPlanNode,
+		public readonly usingColumns?: string[]
+	) {
+		// Cost estimate: base cost is sum of children plus join cost
+		const leftCost = left.getTotalCost();
+		const rightCost = right.getTotalCost();
+		const leftRows = left.estimatedRows ?? 100;
+		const rightRows = right.estimatedRows ?? 100;
+
+		// Simple join cost heuristic - nested loop cost
+		const joinCost = leftRows * rightRows;
+		super(scope, leftCost + rightCost + joinCost);
+
+		this.attributesCache = new Cached(() => this.buildAttributes());
+	}
+
+	private buildAttributes(): Attribute[] {
+		const leftAttrs = this.left.getAttributes();
+		const rightAttrs = this.right.getAttributes();
+
+		// For JOINs, concatenate left and right attributes
+		// For OUTER joins, mark attributes from the nullable side as nullable
+		const attributes: Attribute[] = [];
+
+		// Add left attributes
+		for (const attr of leftAttrs) {
+			const isNullable = this.joinType === 'right' || this.joinType === 'full';
+			attributes.push({
+				...attr,
+				// For right/full outer joins, left side can be null
+				type: isNullable ? { ...attr.type, nullable: true } : attr.type
+			});
+		}
+
+		// Add right attributes
+		for (const attr of rightAttrs) {
+			const isNullable = this.joinType === 'left' || this.joinType === 'full';
+			attributes.push({
+				...attr,
+				// For left/full outer joins, right side can be null
+				type: isNullable ? { ...attr.type, nullable: true } : attr.type
+			});
+		}
+
+		return attributes;
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getType(): RelationType {
+		const leftType = this.left.getType();
+		const rightType = this.right.getType();
+
+		// Combine column types from both sides
+		const leftColumns = leftType.columns;
+		const rightColumns = rightType.columns;
+
+		// For outer joins, mark columns as nullable appropriately
+		const combinedColumns = [
+			...leftColumns.map(col => {
+				const isNullable = this.joinType === 'right' || this.joinType === 'full';
+				return isNullable ? { ...col, type: { ...col.type, nullable: true } } : col;
+			}),
+			...rightColumns.map(col => {
+				const isNullable = this.joinType === 'left' || this.joinType === 'full';
+				return isNullable ? { ...col, type: { ...col.type, nullable: true } } : col;
+			})
+		];
+
+		// Join result is a set only if both inputs are sets and it's an inner/cross join
+		// Outer joins can introduce duplicates due to null padding
+		const isSet = (this.joinType === 'inner' || this.joinType === 'cross') &&
+			         leftType.isSet && rightType.isSet;
+
+		// Combine keys from both sides - for joins this gets complex but we'll keep it simple for now
+		const combinedKeys = [...leftType.keys, ...rightType.keys];
+
+		// Combine row constraints from both sides
+		const combinedRowConstraints = [...leftType.rowConstraints, ...rightType.rowConstraints];
+
+		return {
+			typeClass: 'relation',
+			columns: combinedColumns,
+			isSet,
+			isReadOnly: leftType.isReadOnly && rightType.isReadOnly,
+			keys: combinedKeys,
+			rowConstraints: combinedRowConstraints
+		};
+	}
+
+	getChildren(): readonly PlanNode[] {
+		return this.condition ? [this.left, this.right, this.condition] : [this.left, this.right];
+	}
+
+	getRelations(): readonly [RelationalPlanNode, RelationalPlanNode] {
+		return [this.left, this.right];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		const expectedLength = this.condition ? 3 : 2;
+		if (newChildren.length !== expectedLength) {
+			quereusError(`JoinNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+
+		const [newLeft, newRight, newCondition] = newChildren;
+
+		// Type check
+		if (!('getAttributes' in newLeft) || typeof (newLeft as any).getAttributes !== 'function') {
+			quereusError('JoinNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+		if (!('getAttributes' in newRight) || typeof (newRight as any).getAttributes !== 'function') {
+			quereusError('JoinNode: second child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+		if (newCondition && !('expression' in newCondition)) {
+			quereusError('JoinNode: third child must be a ScalarPlanNode', StatusCode.INTERNAL);
+		}
+
+		// Check if anything changed
+		const leftChanged = newLeft !== this.left;
+		const rightChanged = newRight !== this.right;
+		const conditionChanged = newCondition !== this.condition;
+
+		if (!leftChanged && !rightChanged && !conditionChanged) {
+			return this;
+		}
+
+		// Create new instance - JoinNode creates new attributes by combining left and right
+		return new JoinNode(
+			this.scope,
+			newLeft as RelationalPlanNode,
+			newRight as RelationalPlanNode,
+			this.joinType,
+			newCondition as ScalarPlanNode | undefined,
+			this.usingColumns
+		);
+	}
+
+	get estimatedRows(): number | undefined {
+		const leftRows = this.left.estimatedRows;
+		const rightRows = this.right.estimatedRows;
+
+		if (leftRows === undefined || rightRows === undefined) {
+			return undefined;
+		}
+
+		// Simple heuristics for different join types
+		switch (this.joinType) {
+			case 'cross':
+				return leftRows * rightRows;
+			case 'inner':
+				// Assume 10% selectivity for inner joins
+				return Math.max(1, leftRows * rightRows * 0.1);
+			case 'left':
+				// Left joins preserve all left rows
+				return leftRows;
+			case 'right':
+				// Right joins preserve all right rows
+				return rightRows;
+			case 'full':
+				// Full outer joins can have at most left + right rows
+				return leftRows + rightRows;
+			default:
+				return leftRows * rightRows * 0.1;
+		}
+	}
+
+	override toString(): string {
+		const joinTypeDisplay = this.joinType.toUpperCase();
+		if (this.condition) {
+			return `${joinTypeDisplay} JOIN ON condition`;
+		} else if (this.usingColumns) {
+			return `${joinTypeDisplay} JOIN USING(${this.usingColumns.join(', ')})`;
+		} else {
+			return `${joinTypeDisplay} JOIN`;
+		}
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			joinType: this.joinType,
+			hasCondition: !!this.condition,
+			usingColumns: this.usingColumns,
+			leftRows: this.left.estimatedRows,
+			rightRows: this.right.estimatedRows
+		};
+	}
+}

package/src/planner/nodes/limit-offset.ts

@@ -0,0 +1,125 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type ScalarPlanNode, type Attribute } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import { formatExpression } from '../../util/plan-formatter.js';
+import { quereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+/**
+ * Represents a LIMIT/OFFSET operation.
+ * It takes an input relation and returns at most 'limit' rows, skipping 'offset' rows.
+ */
+export class LimitOffsetNode extends PlanNode implements UnaryRelationalNode {
+  override readonly nodeType = PlanNodeType.LimitOffset;
+
+  constructor(
+    scope: Scope,
+    public readonly source: RelationalPlanNode,
+    public readonly limit: ScalarPlanNode | undefined,
+    public readonly offset: ScalarPlanNode | undefined,
+    estimatedCostOverride?: number
+  ) {
+    // Cost is proportional to offset + limit (rows we need to process)
+    // We assume limit and offset are constants, but in practice they could be expressions
+    super(scope, estimatedCostOverride ?? source.getTotalCost());
+  }
+
+  getType(): RelationType {
+    // LIMIT/OFFSET preserves the type of the source relation
+    return this.source.getType();
+  }
+
+  getAttributes(): Attribute[] {
+    // LIMIT/OFFSET preserves the same attributes as its source
+    return this.source.getAttributes();
+  }
+
+  getChildren(): readonly PlanNode[] {
+    const children: PlanNode[] = [this.source];
+    if (this.limit) children.push(this.limit);
+    if (this.offset) children.push(this.offset);
+    return children;
+  }
+
+  getRelations(): readonly [RelationalPlanNode] {
+    return [this.source];
+  }
+
+  get estimatedRows(): number | undefined {
+    const sourceRows = this.source.estimatedRows;
+    if (sourceRows === undefined) return undefined;
+
+    // TODO: Evaluate limit/offset if they are constants
+    // For now, assume limit is 100 if specified, otherwise use source rows
+    if (this.limit) {
+      return Math.min(sourceRows, 100);
+    }
+    return sourceRows;
+  }
+
+  override toString(): string {
+    const parts: string[] = [];
+    if (this.limit) parts.push(`LIMIT ${formatExpression(this.limit)}`);
+    if (this.offset) parts.push(`OFFSET ${formatExpression(this.offset)}`);
+    return parts.join(' ');
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {};
+
+    if (this.limit) {
+      props.limit = formatExpression(this.limit);
+    }
+
+    if (this.offset) {
+      props.offset = formatExpression(this.offset);
+    }
+
+    return props;
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    const expectedLength = 1 + (this.limit ? 1 : 0) + (this.offset ? 1 : 0);
+    if (newChildren.length !== expectedLength) {
+      quereusError(`LimitOffsetNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
+    }
+
+    const [newSource, ...restChildren] = newChildren;
+
+    // Type check
+    if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+      quereusError('LimitOffsetNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+    }
+
+    // Parse optional limit and offset from remaining children
+    let newLimit: ScalarPlanNode | undefined = undefined;
+    let newOffset: ScalarPlanNode | undefined = undefined;
+    let childIndex = 0;
+
+    if (this.limit) {
+      newLimit = restChildren[childIndex] as ScalarPlanNode;
+      childIndex++;
+    }
+    if (this.offset) {
+      newOffset = restChildren[childIndex] as ScalarPlanNode;
+    }
+
+    // Check if anything changed
+    const sourceChanged = newSource !== this.source;
+    const limitChanged = newLimit !== this.limit;
+    const offsetChanged = newOffset !== this.offset;
+
+    if (!sourceChanged && !limitChanged && !offsetChanged) {
+      return this;
+    }
+
+    // Create new instance preserving attributes (limit/offset preserves source attributes)
+    return new LimitOffsetNode(
+      this.scope,
+      newSource as RelationalPlanNode,
+      newLimit,
+      newOffset
+    );
+  }
+}

package/src/planner/nodes/physical-access-nodes.ts

@@ -0,0 +1,298 @@
+/**
+* Physical table access nodes for seek and range scan operations
+ * These replace logical TableScanNode during optimization
+ */
+
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type UnaryRelationalNode, type PhysicalProperties, type Attribute } from './plan-node.js';
+import { TableReferenceNode } from './reference.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import { Cached } from '../../util/cached.js';
+import type { FilterInfo } from '../../vtab/filter-info.js';
+import type { ScalarPlanNode } from './plan-node.js';
+
+/**
+ * Base class for physical table access operations
+ * Provides common functionality for sequential scan, index scan, and index seek
+ */
+export abstract class PhysicalTableAccessNode extends PlanNode implements UnaryRelationalNode {
+	private attributesCache: Cached<Attribute[]>;
+	private outputType: Cached<RelationType>;
+
+	constructor(
+		scope: Scope,
+		public readonly source: TableReferenceNode,
+		public readonly filterInfo: FilterInfo,
+		estimatedCostOverride?: number
+	) {
+		super(scope, estimatedCostOverride ?? filterInfo.indexInfoOutput.estimatedCost);
+
+		this.attributesCache = new Cached(() => this.source.getAttributes());
+		this.outputType = new Cached(() => this.source.getType());
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getType(): RelationType {
+		return this.outputType.value;
+	}
+
+	getChildren(): readonly PlanNode[] {
+		return [this.source];
+	}
+
+	getRelations(): readonly [TableReferenceNode] {
+		return [this.source];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 1) {
+			throw new Error(`${this.nodeType} expects 1 child, got ${newChildren.length}`);
+		}
+
+		const [newSource] = newChildren;
+
+		// Type check - Physical access nodes specifically need a TableReferenceNode
+		if (!(newSource instanceof TableReferenceNode)) {
+			throw new Error(`${this.nodeType}: child must be a TableReferenceNode`);
+		}
+
+		// Return same instance if nothing changed
+		if (newSource === this.source) {
+			return this;
+		}
+
+		// Subclasses must override this with their specific constructor
+		throw new Error(`${this.nodeType} must override withChildren method`);
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			table: this.source.tableSchema.name,
+			schema: this.source.tableSchema.schemaName,
+			accessMethod: this.nodeType,
+			filterInfo: {
+				usableIndex: this.filterInfo.indexInfoOutput.idxStr,
+				matchedClauses: this.filterInfo.indexInfoOutput.aConstraintUsage?.length || 0,
+				estimatedCost: this.filterInfo.indexInfoOutput.estimatedCost,
+				estimatedRows: this.filterInfo.indexInfoOutput.estimatedRows
+			}
+		};
+	}
+}
+
+/**
+ * Sequential scan - reads entire table without using indexes
+ * Used when no suitable index exists or for small tables
+ */
+export class SeqScanNode extends PhysicalTableAccessNode {
+	override readonly nodeType = PlanNodeType.SeqScan;
+
+	computePhysical(): Partial<PhysicalProperties> {
+		return {
+			estimatedRows: this.source.estimatedRows,
+			uniqueKeys: this.source.getType().keys.map(key => key.map(colRef => colRef.index)),
+			// Sequential scans don't provide any specific ordering
+			ordering: undefined
+		};
+	}
+
+	override toString(): string {
+		return `SEQ SCAN ${this.source.tableSchema.name}`;
+	}
+
+	override withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 1) {
+			throw new Error(`SeqScanNode expects 1 child, got ${newChildren.length}`);
+		}
+
+		const [newSource] = newChildren;
+
+		// Type check - Physical access nodes specifically need a TableReferenceNode
+		if (!(newSource instanceof TableReferenceNode)) {
+			throw new Error('SeqScanNode: child must be a TableReferenceNode');
+		}
+
+		// Return same instance if nothing changed
+		if (newSource === this.source) {
+			return this;
+		}
+
+		// Create new instance
+		return new SeqScanNode(
+			this.scope,
+			newSource,
+			this.filterInfo
+		);
+	}
+}
+
+/**
+ * Index scan - uses an index to read table data in order
+ * Provides ordering and can handle range queries efficiently
+ */
+export class IndexScanNode extends PhysicalTableAccessNode {
+	override readonly nodeType = PlanNodeType.IndexScan;
+
+	constructor(
+		scope: Scope,
+		source: TableReferenceNode,
+		filterInfo: FilterInfo,
+		public readonly indexName: string,
+		public readonly providesOrdering?: { column: number; desc: boolean }[],
+		estimatedCostOverride?: number
+	) {
+		super(scope, source, filterInfo, estimatedCostOverride);
+	}
+
+	computePhysical(): Partial<PhysicalProperties> {
+		return {
+			estimatedRows: this.source.estimatedRows,
+			uniqueKeys: this.source.getType().keys.map(key => key.map(colRef => colRef.index)),
+			// Index scans can provide ordering
+			ordering: this.providesOrdering
+		};
+	}
+
+	override toString(): string {
+		const orderDesc = this.providesOrdering
+			? ` ORDER BY ${this.providesOrdering.map(o => `${o.column}${o.desc ? ' DESC' : ''}`).join(', ')}`
+			: '';
+		return `INDEX SCAN ${this.source.tableSchema.name} USING ${this.indexName}${orderDesc}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			...super.getLogicalAttributes(),
+			indexName: this.indexName,
+			providesOrdering: this.providesOrdering
+		};
+	}
+
+	override withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 1) {
+			throw new Error(`IndexScanNode expects 1 child, got ${newChildren.length}`);
+		}
+
+		const [newSource] = newChildren;
+
+		// Type check - Physical access nodes specifically need a TableReferenceNode
+		if (!(newSource instanceof TableReferenceNode)) {
+			throw new Error('IndexScanNode: child must be a TableReferenceNode');
+		}
+
+		// Return same instance if nothing changed
+		if (newSource === this.source) {
+			return this;
+		}
+
+		// Create new instance
+		return new IndexScanNode(
+			this.scope,
+			newSource,
+			this.filterInfo,
+			this.indexName,
+			this.providesOrdering
+		);
+	}
+}
+
+/**
+ * Index seek - point lookup or tight range using an index
+ * Very efficient for equality constraints and small ranges
+ */
+export class IndexSeekNode extends PhysicalTableAccessNode {
+	override readonly nodeType = PlanNodeType.IndexSeek;
+
+	constructor(
+		scope: Scope,
+		source: TableReferenceNode,
+		filterInfo: FilterInfo,
+		public readonly indexName: string,
+		public readonly seekKeys: ScalarPlanNode[],
+		public readonly isRange: boolean = false,
+		public readonly providesOrdering?: { column: number; desc: boolean }[],
+		estimatedCostOverride?: number
+	) {
+		super(scope, source, filterInfo, estimatedCostOverride);
+	}
+
+	computePhysical(): Partial<PhysicalProperties> {
+		return {
+			uniqueKeys: this.source.getType().keys.map(key => key.map(colRef => colRef.index)),
+			// Index seeks can provide ordering and usually return few rows
+			ordering: this.providesOrdering,
+			// Seeks typically return much fewer rows than estimated
+			estimatedRows: Math.min(this.source.estimatedRows || 1000, 100)
+		};
+	}
+
+	override toString(): string {
+		const seekDesc = this.isRange ? 'RANGE' : 'SEEK';
+		const orderDesc = this.providesOrdering
+			? ` ORDER BY ${this.providesOrdering.map(o => `${o.column}${o.desc ? ' DESC' : ''}`).join(', ')}`
+			: '';
+		return `INDEX ${seekDesc} ${this.source.tableSchema.name} USING ${this.indexName}${orderDesc}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			...super.getLogicalAttributes(),
+			indexName: this.indexName,
+			seekKeys: this.seekKeys.map(key => key.toString()),
+			isRange: this.isRange,
+			providesOrdering: this.providesOrdering
+		};
+	}
+
+	getSeekKeys(): readonly ScalarPlanNode[] {
+		return this.seekKeys;
+	}
+
+	override getChildren(): readonly PlanNode[] {
+		return [this.source, ...this.seekKeys];
+	}
+
+	override withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		const expectedLength = 1 + this.seekKeys.length;
+		if (newChildren.length !== expectedLength) {
+			throw new Error(`IndexSeekNode expects ${expectedLength} children, got ${newChildren.length}`);
+		}
+
+		const [newSource, ...newSeekKeys] = newChildren;
+
+		// Type check - Physical access nodes specifically need a TableReferenceNode
+		if (!(newSource instanceof TableReferenceNode)) {
+			throw new Error('IndexSeekNode: first child must be a TableReferenceNode');
+		}
+
+		// Type check seek keys
+		for (const seekKey of newSeekKeys) {
+			if (!('expression' in seekKey)) {
+				throw new Error('IndexSeekNode: seek keys must be ScalarPlanNodes');
+			}
+		}
+
+		// Check if anything changed
+		const sourceChanged = newSource !== this.source;
+		const seekKeysChanged = newSeekKeys.some((key, i) => key !== this.seekKeys[i]);
+
+		if (!sourceChanged && !seekKeysChanged) {
+			return this;
+		}
+
+		// Create new instance
+		return new IndexSeekNode(
+			this.scope,
+			newSource,
+			this.filterInfo,
+			this.indexName,
+			newSeekKeys as ScalarPlanNode[],
+			this.isRange,
+			this.providesOrdering
+		);
+	}
+}