@quereus/quereus 0.1.0

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

@@ -0,0 +1,223 @@
+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 { Cached } from '../../util/cached.js';
+import { expressionToString } from '../../util/ast-stringify.js';
+import { formatProjection } from '../../util/plan-formatter.js';
+import { ColumnReferenceNode } from './reference.js';
+import { quereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+export interface Projection {
+	node: ScalarPlanNode;
+	alias?: string;
+	/** Optional predefined attribute ID to preserve during optimization */
+	attributeId?: number;
+}
+
+/**
+ * Represents a projection operation (SELECT list) without DISTINCT.
+ * It takes an input relation and outputs a new relation with specified columns/expressions.
+ */
+export class ProjectNode extends PlanNode implements UnaryRelationalNode {
+	override readonly nodeType = PlanNodeType.Project;
+
+	private outputTypeCache: Cached<RelationType>;
+	private attributesCache: Cached<Attribute[]>;
+
+	constructor(
+		scope: Scope,
+		public readonly source: RelationalPlanNode,
+		public readonly projections: ReadonlyArray<Projection>,
+		estimatedCostOverride?: number,
+		/** Optional predefined attributes for preserving IDs during optimization */
+		predefinedAttributes?: Attribute[]
+	) {
+		super(scope, estimatedCostOverride);
+
+		const sourceType = this.source.getType();
+
+		this.outputTypeCache = new Cached(() => {
+			// Build column names with proper duplicate handling
+			const columnNames: string[] = [];
+			const nameCount = new Map<string, number>();
+
+			const columns = this.projections.map((proj) => {
+				// Determine base column name
+				let baseName: string;
+				if (proj.alias) {
+					baseName = proj.alias;
+				} else if (proj.node instanceof ColumnReferenceNode) {
+					// For column references, use the unqualified column name
+					baseName = proj.node.expression.name;
+				} else {
+					// For expressions, use the string representation
+					baseName = expressionToString(proj.node.expression);
+				}
+
+				// Handle duplicate names
+				let finalName: string;
+				const currentCount = nameCount.get(baseName) || 0;
+				if (currentCount === 0) {
+					// First occurrence - use the base name
+					finalName = baseName;
+				} else {
+					// Subsequent occurrences - add numbered suffix
+					finalName = `${baseName}:${currentCount}`;
+				}
+				nameCount.set(baseName, currentCount + 1);
+				columnNames.push(finalName);
+
+				return {
+					name: finalName,
+					type: proj.node.getType(),
+					generated: proj.node.nodeType !== PlanNodeType.ColumnReference,
+				};
+			});
+
+			return {
+				typeClass: 'relation',
+				isReadOnly: sourceType.isReadOnly,
+				isSet: sourceType.isSet,
+				columns,
+				// TODO: Infer keys based on DISTINCT and projection's effect on input keys
+				keys: [],
+				// TODO: propagate row constraints that don't have projected off columns
+				rowConstraints: [],
+			} as RelationType;
+		});
+
+		this.attributesCache = new Cached(() => {
+			// If predefined attributes are provided, use them (for optimization)
+			if (predefinedAttributes) {
+				return predefinedAttributes;
+			}
+
+			// Get the computed column names from the type
+			const outputType = this.getType();
+
+			// For each projection, preserve attribute ID if it's a simple column reference
+			return this.projections.map((proj, index) => {
+				// Check if projection has a predefined attribute ID
+				if (proj.attributeId !== undefined) {
+					return {
+						id: proj.attributeId,
+						name: outputType.columns[index].name,
+						type: proj.node.getType(),
+						sourceRelation: `${this.nodeType}:${this.id}`
+					};
+				}
+
+				// If this projection is a simple column reference, preserve its attribute ID
+				if (proj.node instanceof ColumnReferenceNode) {
+					return {
+						id: proj.node.attributeId,
+						name: outputType.columns[index].name, // Use the deduplicated name
+						type: proj.node.getType(),
+						sourceRelation: `${this.nodeType}:${this.id}`
+					};
+				} else {
+					// For computed expressions, generate new attribute ID
+					return {
+						id: PlanNode.nextAttrId(),
+						name: outputType.columns[index].name, // Use the deduplicated name
+						type: proj.node.getType(),
+						sourceRelation: `${this.nodeType}:${this.id}`
+					};
+				}
+			});
+		});
+	}
+
+	getType(): RelationType {
+		return this.outputTypeCache.value;
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getProducingExprs(): Map<number, ScalarPlanNode> {
+		const attributes = this.getAttributes();
+		const map = new Map<number, ScalarPlanNode>();
+
+		for (let i = 0; i < this.projections.length; i++) {
+			const proj = this.projections[i];
+			const attr = attributes[i];
+			if (attr) {
+				map.set(attr.id, proj.node);
+			}
+		}
+
+		return map;
+	}
+
+	getChildren(): readonly PlanNode[] {
+		return [this.source, ...this.projections.map(p => p.node)];
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	get estimatedRows(): number | undefined {
+		return this.source.estimatedRows; // Projection doesn't change row count - use DistinctNode to handle DISTINCT
+	}
+
+	override toString(): string {
+		const projectionStrings = this.projections.map(p =>
+			formatProjection(p.node, p.alias)
+		).join(', ');
+		return `SELECT ${projectionStrings}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			projections: this.projections.map(p => ({
+				expression: expressionToString(p.node.expression),
+				alias: p.alias
+			}))
+		};
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 1 + this.projections.length) {
+			quereusError(`ProjectNode expects ${1 + this.projections.length} children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+
+		const [newSource, ...newProjectionNodes] = newChildren;
+
+		// Type check
+		if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+			quereusError('ProjectNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+
+		// Check if anything changed
+		const sourceChanged = newSource !== this.source;
+		const projectionsChanged = newProjectionNodes.some((node, i) => node !== this.projections[i].node);
+
+		if (!sourceChanged && !projectionsChanged) {
+			return this;
+		}
+
+		// **CRITICAL**: Preserve original attribute IDs to maintain column reference stability
+		const originalAttributes = this.getAttributes();
+
+		// Build new projections array with preserved attribute IDs
+		const newProjections = newProjectionNodes.map((node, i) => ({
+			node: node as ScalarPlanNode,
+			alias: this.projections[i].alias,
+			attributeId: originalAttributes[i].id // Preserve original attribute ID
+		}));
+
+		// Create new instance with predefined attributes
+		return new ProjectNode(
+			this.scope,
+			newSource as RelationalPlanNode,
+			newProjections,
+			undefined, // estimatedCostOverride
+			originalAttributes // Pass original attributes to preserve IDs
+		);
+	}
+}

package/src/planner/nodes/recursive-cte-node.ts

@@ -0,0 +1,130 @@
+import { PlanNode, type RelationalPlanNode, type Attribute, type TableDescriptor } 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 type { CTEPlanNode } from './cte-node.js';
+
+/**
+ * Plan node for Recursive Common Table Expressions.
+ * This handles the special structure of recursive CTEs with base and recursive cases.
+ */
+export class RecursiveCTENode extends PlanNode implements CTEPlanNode {
+	readonly nodeType = PlanNodeType.RecursiveCTE;
+	readonly isRecursive = true; // Always true for recursive CTEs
+	readonly tableDescriptor: TableDescriptor = {}; // Identity object for table context lookup
+
+	private attributesCache: Cached<Attribute[]>;
+	private typeCache: Cached<RelationType>;
+	private _recursiveCaseQuery: RelationalPlanNode;
+
+	constructor(
+		scope: Scope,
+		public readonly cteName: string,
+		public readonly columns: string[] | undefined,
+		public readonly baseCaseQuery: RelationalPlanNode,
+		recursiveCaseQuery: RelationalPlanNode,
+		public readonly isUnionAll: boolean,
+		public readonly materializationHint: 'materialized' | 'not_materialized' | undefined = 'materialized',
+		public readonly maxRecursion?: number
+	) {
+		super(scope, baseCaseQuery.getTotalCost() + recursiveCaseQuery.getTotalCost() + 50); // Higher cost for recursion
+		this._recursiveCaseQuery = recursiveCaseQuery;
+		this.attributesCache = new Cached(() => this.buildAttributes());
+		this.typeCache = new Cached(() => this.buildType());
+	}
+
+	get recursiveCaseQuery(): RelationalPlanNode {
+		return this._recursiveCaseQuery;
+	}
+
+	/**
+	 * Sets the recursive case query after construction.
+	 * This is needed to handle the circular dependency during planning.
+	 */
+	setRecursiveCaseQuery(query: RelationalPlanNode): void {
+		this._recursiveCaseQuery = query;
+		// Clear caches since they might depend on the recursive case
+		this.attributesCache = new Cached(() => this.buildAttributes());
+		this.typeCache = new Cached(() => this.buildType());
+	}
+
+	private buildAttributes(): Attribute[] {
+		// Use the base case query's attributes as the template
+		const baseCaseAttributes = this.baseCaseQuery.getAttributes();
+
+		// Use explicit column names if provided, otherwise use base case column names
+		const baseCaseType = this.baseCaseQuery.getType();
+		const columnNames = this.columns || baseCaseType.columns.map((c: any) => c.name);
+
+		return baseCaseAttributes.map((attr: any, index: number) => ({
+			id: PlanNode.nextAttrId(),
+			name: columnNames[index] || attr.name,
+			type: attr.type,
+			sourceRelation: `recursive_cte:${this.cteName}`
+		}));
+	}
+
+	private buildType(): RelationType {
+		return {
+			typeClass: 'relation',
+			isReadOnly: false,
+			isSet: !this.isUnionAll, // UNION creates a set, UNION ALL creates a bag
+			columns: this.getAttributes().map((attr: any) => ({
+				name: attr.name,
+				type: attr.type
+			})),
+			keys: [], // Recursive CTEs don't have inherent keys
+			rowConstraints: []
+		};
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	// For recursive CTEs, we consider the base case as the primary source
+	get source(): RelationalPlanNode {
+		return this.baseCaseQuery;
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.baseCaseQuery];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			throw new Error(`RecursiveCTENode expects 0 children, got ${newChildren.length}`);
+		}
+		return this; // No children in getChildren(), sources are accessed via getRelations()
+	}
+
+	override toString(): string {
+		const recursiveText = 'RECURSIVE ';
+		const columnsText = this.columns ? `(${this.columns.join(', ')})` : '';
+		const unionText = this.isUnionAll ? 'UNION ALL' : 'UNION';
+		const materializationText = this.materializationHint ? ` ${this.materializationHint.toUpperCase()}` : '';
+		return `${recursiveText}CTE ${this.cteName}${columnsText} [${unionText}]${materializationText}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			cteName: this.cteName,
+			columns: this.columns,
+			isUnionAll: this.isUnionAll,
+			materializationHint: this.materializationHint,
+			isRecursive: true,
+			maxRecursion: this.maxRecursion,
+			baseCaseType: this.baseCaseQuery.getType(),
+			recursiveCaseType: this.recursiveCaseQuery.getType()
+		};
+	}
+}

package/src/planner/nodes/reference.ts

@@ -0,0 +1,310 @@
+import type { BaseType, ScalarType, RelationType } from '../../common/datatype.js';
+import { PlanNode, type ZeroAryRelationalNode, type ZeroAryScalarNode, type Attribute } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableSchema } from '../../schema/table.js';
+import type { Scope } from '../scopes/scope.js';
+import type * as AST from '../../parser/ast.js';
+import { relationTypeFromTableSchema } from '../type-utils.js';
+import { Cached } from '../../util/cached.js';
+import type { FunctionSchema } from '../../schema/function.js';
+import { isTableValuedFunctionSchema } from '../../schema/function.js';
+import { formatScalarType } from '../../util/plan-formatter.js';
+import { quereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import type { VirtualTableModule } from '../../vtab/module.js';
+
+/** Represents a reference to a table in the global schema. */
+export class TableReferenceNode extends PlanNode implements ZeroAryRelationalNode {
+	override readonly nodeType = PlanNodeType.TableReference;
+
+	private typeCache: Cached<RelationType>;
+	private attributesCache: Cached<Attribute[]>;
+
+	constructor(
+		scope: Scope,
+		public readonly tableSchema: TableSchema,
+		public readonly vtabModule: VirtualTableModule<any, any>,
+		public readonly vtabAuxData?: unknown,
+		estimatedCostOverride?: number
+	) {
+		super(scope, estimatedCostOverride ?? 1);
+		this.typeCache = new Cached(() => relationTypeFromTableSchema(tableSchema));
+		this.attributesCache = new Cached(() => {
+			// Create attributes from table schema columns
+			return this.tableSchema.columns.map((column) => ({
+				id: PlanNode.nextAttrId(),
+				name: column.name,
+				type: {
+					typeClass: 'scalar' as const,
+					affinity: column.affinity,
+					nullable: !column.notNull,
+					isReadOnly: false,
+					collationName: column.collation
+				},
+				sourceRelation: `${this.tableSchema.schemaName}.${this.tableSchema.name}`
+			}));
+		});
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			quereusError(`TableReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+		return this; // No children, so no change
+	}
+
+	get estimatedRows(): number | undefined {
+		return this.tableSchema.estimatedRows;
+	}
+
+	override toString(): string {
+		return `${this.tableSchema.schemaName}.${this.tableSchema.name}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			schema: this.tableSchema.schemaName,
+			table: this.tableSchema.name,
+			columns: this.tableSchema.columns.map(col => col.name),
+			estimates: {
+				rows: this.tableSchema.estimatedRows
+			}
+		};
+	}
+}
+
+export class TableFunctionReferenceNode extends PlanNode implements ZeroAryRelationalNode {
+	override readonly nodeType = PlanNodeType.TableFunctionReference;
+
+	private attributesCache: Cached<Attribute[]>;
+
+	constructor(
+		scope: Scope,
+		public readonly functionSchema: FunctionSchema,
+		estimatedCostOverride?: number
+	) {
+		super(scope, estimatedCostOverride ?? 1);
+
+		this.attributesCache = new Cached(() => {
+			// Create attributes from function schema return type
+			if (isTableValuedFunctionSchema(this.functionSchema)) {
+				return this.functionSchema.returnType.columns.map((column) => ({
+					id: PlanNode.nextAttrId(),
+					name: column.name,
+					type: column.type,
+					sourceRelation: `${this.functionSchema.name}()`
+				}));
+			}
+			return [];
+		});
+	}
+
+	getType(): RelationType {
+		if (isTableValuedFunctionSchema(this.functionSchema)) {
+			return this.functionSchema.returnType;
+		}
+		quereusError(
+			`Function ${this.functionSchema.name} is not a table-valued function`,
+			StatusCode.INTERNAL
+		);
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			quereusError(`TableFunctionReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+		return this; // No children, so no change
+	}
+
+	get estimatedRows(): number | undefined {
+		return 100; // Default estimate for table functions
+	}
+
+	override toString(): string {
+		return `${this.functionSchema.name}()`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		const props: Record<string, unknown> = {
+			function: this.functionSchema.name,
+			numArgs: this.functionSchema.numArgs
+		};
+
+		if (isTableValuedFunctionSchema(this.functionSchema)) {
+			props.columns = this.functionSchema.returnType.columns.map(col => col.name);
+		}
+
+		return props;
+	}
+}
+
+/**
+ * Represents a reference to a column from a relational node.
+ * Uses attribute IDs for stable references across plan transformations.
+ */
+export class ColumnReferenceNode extends PlanNode implements ZeroAryScalarNode {
+	override readonly nodeType = PlanNodeType.ColumnReference;
+
+	constructor(
+		scope: Scope,
+		public readonly expression: AST.ColumnExpr, // Original AST expression for this reference
+		public readonly columnType: ScalarType,
+		public readonly attributeId: number, // Stable attribute ID instead of node reference
+		public readonly columnIndex: number, // Position in the row (for runtime efficiency)
+	) {
+		super(scope, 0);
+	}
+
+	getType(): ScalarType {
+		return this.columnType;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			quereusError(`ColumnReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+		return this; // No children, so no change
+	}
+
+	override toString(): string {
+		const columnName = this.expression.alias ??
+			(this.expression.schema ? this.expression.schema + '.' : '') + this.expression.name;
+		return columnName;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			column: this.expression.alias ?? this.expression.name,
+			schema: this.expression.schema,
+			attributeId: this.attributeId,
+			resultType: formatScalarType(this.columnType)
+		};
+	}
+}
+
+/**
+ * Represents a reference to a parameter (placeholder in a prepared statement).
+ * The actual value will be provided at execution time.
+ */
+export class ParameterReferenceNode extends PlanNode implements ZeroAryScalarNode {
+	override readonly nodeType = PlanNodeType.ParameterReference;
+
+	constructor(
+		scope: Scope,
+		public readonly expression: AST.ParameterExpr, // Original AST expression for this parameter
+		public readonly nameOrIndex: string | number, // Parameter name (e.g., ':foo') or 1-based index
+		public readonly targetType: ScalarType,
+	) {
+		super(scope, 0.01);
+	}
+
+	getType(): ScalarType {
+		return this.targetType;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			quereusError(`ParameterReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+		return this; // No children, so no change
+	}
+
+	override toString(): string {
+		return `:${this.nameOrIndex}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			parameter: this.nameOrIndex,
+			resultType: formatScalarType(this.targetType)
+		};
+	}
+}
+
+export class FunctionReferenceNode extends PlanNode {
+	override readonly nodeType = PlanNodeType.TableFunctionReference;
+
+	constructor(
+		scope: Scope,
+		public readonly functionSchema: FunctionSchema,
+		public readonly targetType: BaseType,
+	) {
+		super(scope);
+	}
+
+	// Type has to be determined by scalar or relation call node
+	getType(): BaseType {
+		return this.targetType;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			quereusError(`FunctionReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+		return this; // No children, so no change
+	}
+
+	override toString(): string {
+		return `${this.functionSchema.name}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			function: this.functionSchema.name,
+			numArgs: this.functionSchema.numArgs,
+			targetType: this.targetType.typeClass
+		};
+	}
+}