@quereus/quereus 0.1.0

package/src/planner/framework/trace.ts

@@ -0,0 +1,259 @@
+/**
+ * Trace framework for Titan optimizer rule execution
+ * Provides debugging hooks and performance monitoring
+ */
+
+import { createLogger } from '../../common/logger.js';
+import type { PlanNode } from '../nodes/plan-node.js';
+import type { RuleHandle } from './registry.js';
+import { isDebugEnabled, isFeatureEnabled } from '../../util/environment.js';
+
+const log = createLogger('optimizer:framework:trace');
+
+/**
+ * Trace hooks for optimizer rule execution
+ */
+export interface TraceHook {
+	/** Called when a rule starts execution */
+	onRuleStart?(handle: RuleHandle, node: PlanNode): void;
+
+	/** Called when a rule completes execution */
+	onRuleEnd?(handle: RuleHandle, before: PlanNode, after: PlanNode | null): void;
+
+	/** Called when optimizer starts processing a node */
+	onNodeStart?(node: PlanNode): void;
+
+	/** Called when optimizer finishes processing a node */
+	onNodeEnd?(before: PlanNode, after: PlanNode): void;
+
+	/** Called when optimization phase starts */
+	onPhaseStart?(phase: string): void;
+
+	/** Called when optimization phase ends */
+	onPhaseEnd?(phase: string): void;
+}
+
+/**
+ * Default trace hook that logs to debug channels
+ */
+export class DebugTraceHook implements TraceHook {
+	private readonly ruleLog = createLogger('optimizer:trace:rules');
+	private readonly nodeLog = createLogger('optimizer:trace:nodes');
+	private readonly phaseLog = createLogger('optimizer:trace:phases');
+
+	onRuleStart(handle: RuleHandle, node: PlanNode): void {
+		this.ruleLog('→ %s starting on %s#%s', handle.id, node.nodeType, node.id);
+	}
+
+	onRuleEnd(handle: RuleHandle, before: PlanNode, after: PlanNode | null): void {
+		if (after && after !== before) {
+			this.ruleLog('✓ %s transformed %s#%s → %s#%s',
+				handle.id, before.nodeType, before.id, after.nodeType, after.id);
+		} else {
+			this.ruleLog('– %s not applicable to %s#%s', handle.id, before.nodeType, before.id);
+		}
+	}
+
+	onNodeStart(node: PlanNode): void {
+		this.nodeLog('Processing node %s#%s', node.nodeType, node.id);
+	}
+
+	onNodeEnd(before: PlanNode, after: PlanNode): void {
+		if (before !== after) {
+			this.nodeLog('Node %s#%s → %s#%s',
+				before.nodeType, before.id, after.nodeType, after.id);
+		}
+	}
+
+	onPhaseStart(phase: string): void {
+		this.phaseLog('Starting phase: %s', phase);
+	}
+
+	onPhaseEnd(phase: string): void {
+		this.phaseLog('Completed phase: %s', phase);
+	}
+}
+
+/**
+ * Performance monitoring trace hook
+ */
+export class PerformanceTraceHook implements TraceHook {
+	private readonly perfLog = createLogger('optimizer:trace:performance');
+	private ruleStartTimes = new Map<string, number>();
+	private phaseStartTimes = new Map<string, number>();
+
+	onRuleStart(handle: RuleHandle, node: PlanNode): void {
+		const key = `${handle.id}:${node.id}`;
+		this.ruleStartTimes.set(key, performance.now());
+	}
+
+	onRuleEnd(handle: RuleHandle, before: PlanNode, _after: PlanNode | null): void {
+		const key = `${handle.id}:${before.id}`;
+		const startTime = this.ruleStartTimes.get(key);
+		if (startTime !== undefined) {
+			const duration = performance.now() - startTime;
+			this.perfLog('Rule %s took %.2fms on %s#%s',
+				handle.id, duration, before.nodeType, before.id);
+			this.ruleStartTimes.delete(key);
+		}
+	}
+
+	onPhaseStart(phase: string): void {
+		this.phaseStartTimes.set(phase, performance.now());
+	}
+
+	onPhaseEnd(phase: string): void {
+		const startTime = this.phaseStartTimes.get(phase);
+		if (startTime !== undefined) {
+			const duration = performance.now() - startTime;
+			this.perfLog('Phase %s took %.2fms', phase, duration);
+			this.phaseStartTimes.delete(phase);
+		}
+	}
+}
+
+/**
+ * Composite trace hook that combines multiple hooks
+ */
+export class CompositeTraceHook implements TraceHook {
+	constructor(private readonly hooks: TraceHook[]) {}
+
+	onRuleStart(handle: RuleHandle, node: PlanNode): void {
+		for (const hook of this.hooks) {
+			hook.onRuleStart?.(handle, node);
+		}
+	}
+
+	onRuleEnd(handle: RuleHandle, before: PlanNode, after: PlanNode | null): void {
+		for (const hook of this.hooks) {
+			hook.onRuleEnd?.(handle, before, after);
+		}
+	}
+
+	onNodeStart(node: PlanNode): void {
+		for (const hook of this.hooks) {
+			hook.onNodeStart?.(node);
+		}
+	}
+
+	onNodeEnd(before: PlanNode, after: PlanNode): void {
+		for (const hook of this.hooks) {
+			hook.onNodeEnd?.(before, after);
+		}
+	}
+
+	onPhaseStart(phase: string): void {
+		for (const hook of this.hooks) {
+			hook.onPhaseStart?.(phase);
+		}
+	}
+
+	onPhaseEnd(phase: string): void {
+		for (const hook of this.hooks) {
+			hook.onPhaseEnd?.(phase);
+		}
+	}
+}
+
+/**
+ * Global trace hook registry
+ */
+class TraceRegistry {
+	private currentHook: TraceHook | undefined;
+
+	setTraceHook(hook: TraceHook | undefined): void {
+		this.currentHook = hook;
+		if (hook) {
+			log('Trace hook activated');
+		} else {
+			log('Trace hook deactivated');
+		}
+	}
+
+	getCurrentHook(): TraceHook | undefined {
+		return this.currentHook;
+	}
+
+	/**
+	 * Set up default tracing based on environment variables
+	 */
+	setupDefaultTracing(): void {
+		const hooks: TraceHook[] = [];
+
+		// Enable debug tracing if debug logging is enabled
+		if (isDebugEnabled('optimizer')) {
+			hooks.push(new DebugTraceHook());
+		}
+
+		// Enable performance tracing if requested
+		if (isFeatureEnabled('QUEREUS_OPTIMIZER_PERF')) {
+			hooks.push(new PerformanceTraceHook());
+		}
+
+		if (hooks.length > 0) {
+			this.setTraceHook(new CompositeTraceHook(hooks));
+		}
+	}
+}
+
+/**
+ * Global trace registry instance
+ */
+const globalTraceRegistry = new TraceRegistry();
+
+/**
+ * Set the global trace hook
+ */
+export function setTraceHook(hook: TraceHook | undefined): void {
+	globalTraceRegistry.setTraceHook(hook);
+}
+
+/**
+ * Get the current trace hook
+ */
+export function getCurrentTraceHook(): TraceHook | undefined {
+	return globalTraceRegistry.getCurrentHook();
+}
+
+/**
+ * Set up default tracing based on environment
+ */
+export function setupDefaultTracing(): void {
+	globalTraceRegistry.setupDefaultTracing();
+}
+
+/**
+ * Helper functions for calling trace hooks
+ */
+export function traceRuleStart(handle: RuleHandle, node: PlanNode): void {
+	const hook = getCurrentTraceHook();
+	hook?.onRuleStart?.(handle, node);
+}
+
+export function traceRuleEnd(handle: RuleHandle, before: PlanNode, after: PlanNode | null): void {
+	const hook = getCurrentTraceHook();
+	hook?.onRuleEnd?.(handle, before, after);
+}
+
+export function traceNodeStart(node: PlanNode): void {
+	const hook = getCurrentTraceHook();
+	hook?.onNodeStart?.(node);
+}
+
+export function traceNodeEnd(before: PlanNode, after: PlanNode): void {
+	const hook = getCurrentTraceHook();
+	hook?.onNodeEnd?.(before, after);
+}
+
+export function tracePhaseStart(phase: string): void {
+	const hook = getCurrentTraceHook();
+	hook?.onPhaseStart?.(phase);
+}
+
+export function tracePhaseEnd(phase: string): void {
+	const hook = getCurrentTraceHook();
+	hook?.onPhaseEnd?.(phase);
+}
+
+// Initialize default tracing on module load
+setupDefaultTracing();

package/src/planner/nodes/add-constraint-node.ts

@@ -0,0 +1,58 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableReferenceNode } from './reference.js';
+import type { VoidType } from '../../common/datatype.js';
+import type * as AST from '../../parser/ast.js';
+
+/**
+ * Represents adding a constraint to an existing table.
+ * This is a DDL operation that modifies the table schema at runtime.
+ */
+export class AddConstraintNode extends PlanNode implements VoidNode {
+  override readonly nodeType = PlanNodeType.AddConstraint;
+
+  constructor(
+    scope: Scope,
+    public readonly table: TableReferenceNode,
+    public readonly constraint: AST.TableConstraint,
+  ) {
+    super(scope);
+  }
+
+  getType(): VoidType {
+    return { typeClass: 'void' };
+  }
+
+  getRelations(): readonly [TableReferenceNode] {
+    return [this.table];
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 0) {
+      throw new Error(`AddConstraintNode expects 0 children, got ${newChildren.length}`);
+    }
+    return this; // No children, so no change
+  }
+
+  override toString(): string {
+    const constraintType = this.constraint.type.toUpperCase();
+    const constraintName = this.constraint.name || 'unnamed';
+    return `ADD CONSTRAINT ${constraintName} ${constraintType}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName,
+      constraintType: this.constraint.type,
+      constraintName: this.constraint.name,
+      hasOperations: !!this.constraint.operations,
+      operations: this.constraint.operations,
+    };
+  }
+}

package/src/planner/nodes/aggregate-function.ts

@@ -0,0 +1,145 @@
+import type { ScalarType } from '../../common/datatype.js';
+import { PlanNode, type ScalarPlanNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import type { FunctionSchema } from '../../schema/function.js';
+import { isAggregateFunctionSchema } from '../../schema/function.js';
+import type * as AST from '../../parser/ast.js';
+import { formatExpressionList, formatScalarType } from '../../util/plan-formatter.js';
+
+/**
+ * Represents an aggregate function call within a SQL query.
+ * This is specifically for aggregate functions (COUNT, SUM, AVG, etc.)
+ */
+export class AggregateFunctionCallNode extends PlanNode implements ScalarPlanNode {
+	readonly nodeType = PlanNodeType.ScalarFunctionCall; // Using same type as scalar functions
+
+	constructor(
+		scope: Scope,
+		public readonly expression: AST.FunctionExpr,
+		public readonly functionName: string,
+		public readonly functionSchema: FunctionSchema,
+		public readonly args: ReadonlyArray<ScalarPlanNode>,
+		public readonly isDistinct: boolean = false,
+		public readonly orderBy?: ReadonlyArray<{ expression: ScalarPlanNode; direction: 'asc' | 'desc' }>,
+		public readonly filter?: ScalarPlanNode
+	) {
+		super(scope);
+	}
+
+	getType(): ScalarType {
+		// Get the return type from the function schema
+		if (isAggregateFunctionSchema(this.functionSchema)) {
+			return this.functionSchema.returnType;
+		}
+
+		// Fallback for non-aggregate functions (shouldn't happen)
+		return {
+			typeClass: 'scalar',
+			affinity: 0,
+			nullable: true, // Aggregates can return NULL
+			isReadOnly: true
+		};
+	}
+
+	getChildren(): readonly ScalarPlanNode[] {
+		const children: ScalarPlanNode[] = [...this.args];
+		if (this.filter) {
+			children.push(this.filter);
+		}
+		if (this.orderBy) {
+			children.push(...this.orderBy.map(item => item.expression));
+		}
+		return children;
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		const expectedLength = this.args.length + (this.filter ? 1 : 0) + (this.orderBy?.length || 0);
+		if (newChildren.length !== expectedLength) {
+			throw new Error(`AggregateFunctionCallNode expects ${expectedLength} children, got ${newChildren.length}`);
+		}
+
+		// Type check
+		for (const child of newChildren) {
+			if (!('expression' in child)) {
+				throw new Error('AggregateFunctionCallNode: all children must be ScalarPlanNodes');
+			}
+		}
+
+		// Split children back into their respective arrays
+		let childIndex = 0;
+		const newArgs = newChildren.slice(childIndex, childIndex + this.args.length) as ScalarPlanNode[];
+		childIndex += this.args.length;
+
+		let newFilter: ScalarPlanNode | undefined = undefined;
+		if (this.filter) {
+			newFilter = newChildren[childIndex] as ScalarPlanNode;
+			childIndex++;
+		}
+
+		let newOrderBy: ReadonlyArray<{ expression: ScalarPlanNode; direction: 'asc' | 'desc' }> | undefined = undefined;
+		if (this.orderBy?.length) {
+			const newOrderByExpressions = newChildren.slice(childIndex) as ScalarPlanNode[];
+			newOrderBy = this.orderBy.map((item, i) => ({
+				expression: newOrderByExpressions[i],
+				direction: item.direction
+			}));
+		}
+
+		// Check if anything changed
+		const argsChanged = newArgs.some((arg, i) => arg !== this.args[i]);
+		const filterChanged = newFilter !== this.filter;
+		const orderByChanged = newOrderBy && this.orderBy &&
+			newOrderBy.some((item, i) => item.expression !== this.orderBy![i].expression);
+
+		if (!argsChanged && !filterChanged && !orderByChanged) {
+			return this;
+		}
+
+		// Create new instance
+		return new AggregateFunctionCallNode(
+			this.scope,
+			this.expression,
+			this.functionName,
+			this.functionSchema,
+			newArgs,
+			this.isDistinct,
+			newOrderBy,
+			newFilter
+		);
+	}
+
+	override toString(): string {
+		const distinctStr = this.isDistinct ? 'DISTINCT ' : '';
+		const argsStr = formatExpressionList(this.args);
+		const filterStr = this.filter ? ` FILTER (WHERE ${this.filter.toString()})` : '';
+		const orderByStr = this.orderBy?.length ? ` ORDER BY ${this.orderBy.map(item => `${item.expression.toString()} ${item.direction.toUpperCase()}`).join(', ')}` : '';
+		return `${this.functionName}(${distinctStr}${argsStr})${filterStr}${orderByStr}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		const props: Record<string, unknown> = {
+			function: this.functionName,
+			arguments: this.args.map(arg => arg.toString()),
+			resultType: formatScalarType(this.getType()),
+			isDistinct: this.isDistinct
+		};
+
+		if (this.filter) {
+			props.filter = this.filter.toString();
+		}
+
+		if (this.orderBy?.length) {
+			props.orderBy = this.orderBy.map(item => ({
+				expression: item.expression.toString(),
+				direction: item.direction
+			}));
+		}
+
+		return props;
+	}
+}

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

@@ -0,0 +1,220 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, 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 { formatExpressionList } from '../../util/plan-formatter.js';
+import { StatusCode } from '../../common/types.js';
+import { quereusError } from '../../common/errors.js';
+
+export interface AggregateExpression {
+  expression: ScalarPlanNode;
+  alias: string;
+}
+
+/**
+ * Represents an aggregation operation.
+ * It takes an input relation and applies aggregate functions,
+ * optionally grouping by specified expressions.
+ */
+export class AggregateNode extends PlanNode implements UnaryRelationalNode {
+  override readonly nodeType = PlanNodeType.Aggregate;
+
+  private outputTypeCache: Cached<RelationType>;
+  private attributesCache: Cached<Attribute[]>;
+
+  constructor(
+    scope: Scope,
+    public readonly source: RelationalPlanNode,
+    public readonly groupBy: readonly ScalarPlanNode[],
+    public readonly aggregates: readonly AggregateExpression[],
+    estimatedCostOverride?: number,
+    public readonly preserveAttributeIds?: readonly Attribute[]
+  ) {
+    super(scope, estimatedCostOverride ?? source.getTotalCost());
+
+    this.outputTypeCache = new Cached(() => this.buildOutputType());
+    this.attributesCache = new Cached(() => this.buildAttributes());
+  }
+
+  // Helper function to extract a meaningful name from a GROUP BY expression
+  private getGroupByColumnName(expr: ScalarPlanNode, index: number): string {
+    // If it's a column reference, use the column name
+    if (expr.nodeType === PlanNodeType.ColumnReference) {
+      const colRef = expr as any; // ColumnReferenceNode
+      return colRef.expression.name;
+    }
+    // Otherwise, use a generic name
+    return `group_${index}`;
+  }
+
+  private buildOutputType(): RelationType {
+    // Build the output relation type based on group by columns and aggregates
+    const columns = [
+      // Group by columns come first
+      ...this.groupBy.map((expr, index) => ({
+        name: this.getGroupByColumnName(expr, index),
+        type: expr.getType(),
+        generated: false
+      })),
+      // Then aggregate columns
+      ...this.aggregates.map(agg => ({
+        name: agg.alias,
+        type: agg.expression.getType(),
+        generated: true
+      }))
+    ];
+
+    // Determine if result is a set
+    // - Without GROUP BY: always produces exactly 1 row, so it's a set
+    // - With GROUP BY: produces one row per unique group, so it's a set
+    const isSet = true;
+
+    return {
+      typeClass: 'relation',
+      columns,
+      keys: [], // No keys for aggregate results
+      rowConstraints: [], // No row constraints for aggregate results
+      isReadOnly: true,
+      isSet
+    };
+  }
+
+  private buildAttributes(): Attribute[] {
+    // If we have preserved attribute IDs, use them
+    if (this.preserveAttributeIds) {
+      return this.preserveAttributeIds.slice(); // Return a copy
+    }
+
+    const attributes: Attribute[] = [];
+
+    // Group by columns come first
+    this.groupBy.forEach((expr, index) => {
+      const name = this.getGroupByColumnName(expr, index);
+      attributes.push({
+        id: PlanNode.nextAttrId(),
+        name,
+        type: expr.getType(),
+        sourceRelation: `${this.nodeType}:${this.id}`
+      });
+    });
+
+    // Then aggregate columns
+    this.aggregates.forEach((agg) => {
+      attributes.push({
+        id: PlanNode.nextAttrId(),
+        name: agg.alias,
+        type: agg.expression.getType(),
+        sourceRelation: `${this.nodeType}:${this.id}`
+      });
+    });
+
+    return attributes;
+  }
+
+  getType(): RelationType {
+    return this.outputTypeCache.value;
+  }
+
+  getAttributes(): Attribute[] {
+    return this.attributesCache.value;
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [this.source, ...this.groupBy, ...this.aggregates.map(agg => agg.expression)];
+  }
+
+  getRelations(): readonly [RelationalPlanNode] {
+    return [this.source];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    const expectedLength = 1 + this.groupBy.length + this.aggregates.length;
+    if (newChildren.length !== expectedLength) {
+      quereusError(`AggregateNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
+    }
+
+    const [newSource, ...restChildren] = newChildren;
+    const newGroupBy = restChildren.slice(0, this.groupBy.length);
+    const newAggregateExpressions = restChildren.slice(this.groupBy.length);
+
+    // Type check
+    if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+      quereusError('AggregateNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+    }
+
+    // Check if anything changed
+    const sourceChanged = newSource !== this.source;
+    const groupByChanged = newGroupBy.some((expr, i) => expr !== this.groupBy[i]);
+    const aggregatesChanged = newAggregateExpressions.some((expr, i) => expr !== this.aggregates[i].expression);
+
+    if (!sourceChanged && !groupByChanged && !aggregatesChanged) {
+      return this;
+    }
+
+    // Build new aggregates array
+    const newAggregates = newAggregateExpressions.map((expr, i) => ({
+      expression: expr as ScalarPlanNode,
+      alias: this.aggregates[i].alias
+    }));
+
+    // Create new instance that preserves original attribute IDs
+    return new AggregateNode(
+      this.scope,
+      newSource as RelationalPlanNode,
+      newGroupBy as ScalarPlanNode[],
+      newAggregates,
+      undefined, // estimatedCostOverride
+      this.getAttributes() // Preserve original attribute IDs
+    );
+  }
+
+  get estimatedRows(): number | undefined {
+    const sourceRows = this.source.estimatedRows;
+    if (sourceRows === undefined) return undefined;
+
+    // If we have GROUP BY, the output rows depend on the number of distinct groups
+    // For now, we'll use a conservative estimate
+    if (this.groupBy.length > 0) {
+      // Estimate that we'll have at most sourceRows/2 groups, but at least 1
+      return Math.max(1, Math.floor(sourceRows / 2));
+    } else {
+      // No GROUP BY means we're aggregating the entire table into a single row
+      return 1;
+    }
+  }
+
+  override toString(): string {
+    const parts: string[] = [];
+
+    if (this.groupBy.length > 0) {
+      parts.push(`GROUP BY ${formatExpressionList(this.groupBy)}`);
+    }
+
+    if (this.aggregates.length > 0) {
+      const aggregatesStr = this.aggregates.map(agg =>
+        `${agg.expression.toString()} AS ${agg.alias}`
+      ).join(', ');
+      parts.push(`AGG ${aggregatesStr}`);
+    }
+
+    return parts.join('  ');
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {};
+
+    if (this.groupBy.length > 0) {
+      props.groupBy = this.groupBy.map(expr => expr.toString());
+    }
+
+    if (this.aggregates.length > 0) {
+      props.aggregates = this.aggregates.map(agg => ({
+        expression: agg.expression.toString(),
+        alias: agg.alias
+      }));
+    }
+
+    return props;
+  }
+}