@quereus/quereus 0.7.3 → 0.7.5

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

@@ -1,323 +0,0 @@
-/**
- * Physical table access nodes for seek and range scan operations
- * These replace logical TableReferenceNode 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';
-import { TableAccessCapable } from '../framework/characteristics.js';
-
-/**
- * Base class for physical table access operations
- * Provides common functionality for sequential scan, index scan, and index seek
- */
-export abstract class TableAccessNode extends PlanNode implements UnaryRelationalNode, TableAccessCapable {
-	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];
-	}
-
-	// TableAccessCapable interface implementation
-	get tableSchema() {
-		return this.source.tableSchema;
-	}
-
-	abstract getAccessMethod(): 'sequential' | 'index-scan' | 'index-seek' | 'virtual';
-
-	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.getAccessMethod(),
-			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 TableAccessNode {
-	override readonly nodeType = PlanNodeType.SeqScan;
-
-	getAccessMethod(): 'sequential' {
-		return 'sequential';
-	}
-
-	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 TableAccessNode {
-	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);
-	}
-
-	getAccessMethod(): 'index-scan' {
-		return 'index-scan';
-	}
-
-	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 TableAccessNode {
-	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);
-	}
-
-	getAccessMethod(): 'index-seek' {
-		return 'index-seek';
-	}
-
-	computePhysical(): Partial<PhysicalProperties> {
-		const base = {
-			uniqueKeys: this.source.getType().keys.map(key => key.map(colRef => colRef.index)),
-			ordering: this.providesOrdering,
-			estimatedRows: Math.min(this.source.estimatedRows || 1000, 100)
-		} as Partial<PhysicalProperties>;
-		if (!this.isRange) {
-			const pk = this.source.tableSchema.primaryKeyDefinition ?? [];
-			if (pk.length > 0 && this.seekKeys.length >= pk.length) {
-				return { ...base, estimatedRows: 1, uniqueKeys: [[]] } as Partial<PhysicalProperties>;
-			}
-		}
-		return base;
-	}
-
-	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
-		);
-	}
-}

package/src/planner/nodes/table-function-call.ts

@@ -1,134 +0,0 @@
-import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type Attribute } from './plan-node.js';
-import type { RelationType } from '../../common/datatype.js';
-import type { Scope } from '../scopes/scope.js';
-import type { FunctionSchema } from '../../schema/function.js';
-import { isTableValuedFunctionSchema } from '../../schema/function.js';
-import { Cached } from '../../util/cached.js';
-import { formatExpressionList } from '../../util/plan-formatter.js';
-
-/**
- * Represents a table-valued function call in the FROM clause.
- * This produces a relation from a function call like query_plan('SELECT ...').
- */
-export class TableFunctionCallNode extends PlanNode implements RelationalPlanNode {
-  override readonly nodeType = PlanNodeType.TableFunctionCall;
-
-  private attributesCache: Cached<Attribute[]>;
-
-  constructor(
-    scope: Scope,
-    public readonly functionName: string,
-    public readonly functionSchema: FunctionSchema,
-    public readonly operands: readonly ScalarPlanNode[],
-    public readonly alias?: string,
-    public readonly aliasColumns?: readonly string[],
-    estimatedCostOverride?: number
-  ) {
-    super(scope, estimatedCostOverride ?? 1); // Default cost for function calls
-
-    this.attributesCache = new Cached(() => {
-      // Create attributes from function schema return type
-      if (isTableValuedFunctionSchema(this.functionSchema)) {
-        const renamed = this.functionSchema.returnType.columns.map((col, i) => ({
-          id: PlanNode.nextAttrId(),
-          name: (this.aliasColumns && this.aliasColumns[i]) ? this.aliasColumns[i] : col.name,
-          type: col.type,
-          sourceRelation: `${this.functionName}()`
-        }));
-        return renamed;
-      }
-      return [];
-    });
-  }
-
-  getType(): RelationType {
-    // Return the function's defined return type
-    if (isTableValuedFunctionSchema(this.functionSchema)) {
-      return this.functionSchema.returnType;
-    }
-
-    // Fallback for non-table-valued functions (shouldn't happen)
-    return {
-      typeClass: 'relation',
-      isReadOnly: true,
-      isSet: false, // Table functions can return duplicate rows (bags)
-      columns: [],
-      keys: [], // Functions don't typically have inherent keys
-      rowConstraints: [],
-    };
-  }
-
-  getAttributes(): Attribute[] {
-    return this.attributesCache.value;
-  }
-
-  getChildren(): readonly ScalarPlanNode[] {
-    return this.operands;
-  }
-
-  getRelations(): readonly [] {
-    return [];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    if (newChildren.length !== this.operands.length) {
-      throw new Error(`TableFunctionCallNode expects ${this.operands.length} children, got ${newChildren.length}`);
-    }
-
-    // Type check
-    for (const child of newChildren) {
-      if (!('expression' in child)) {
-        throw new Error('TableFunctionCallNode: all children must be ScalarPlanNodes');
-      }
-    }
-
-    // Check if anything changed
-    const childrenChanged = newChildren.some((child, i) => child !== this.operands[i]);
-    if (!childrenChanged) {
-      return this;
-    }
-
-    // Create new instance
-    return new TableFunctionCallNode(
-      this.scope,
-      this.functionName,
-      this.functionSchema,
-      newChildren as ScalarPlanNode[],
-      this.alias,
-      this.aliasColumns
-    );
-  }
-
-  get estimatedRows(): number | undefined {
-    // Functions can return variable numbers of rows, so we'll use a default estimate
-    return 10; // Conservative estimate
-  }
-
-  override toString(): string {
-    const argsStr = formatExpressionList(this.operands);
-    const aliasColsStr = this.aliasColumns && this.aliasColumns.length > 0 ? `(${this.aliasColumns.join(', ')})` : '';
-    const aliasStr = this.alias ? ` AS ${this.alias}${aliasColsStr}` : '';
-    return `${this.functionName}(${argsStr})${aliasStr}`;
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    const props: Record<string, unknown> = {
-      function: this.functionName,
-      arguments: this.operands.map(op => op.toString())
-    };
-
-    if (this.alias) {
-      props.alias = this.alias;
-    }
-    if (this.aliasColumns && this.aliasColumns.length > 0) {
-      props.aliasColumns = [...this.aliasColumns];
-    }
-
-    if (isTableValuedFunctionSchema(this.functionSchema)) {
-      props.columns = this.functionSchema.returnType.columns.map(col => col.name);
-    }
-
-    return props;
-  }
-}

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

@@ -1,55 +0,0 @@
-import { VoidNode } from './plan-node.js';
-import { PlanNodeType } from './plan-node-type.js';
-import type { Scope } from '../scopes/scope.js';
-import * as AST from '../../parser/ast.js';
-import { astToString } from '../../util/ast-stringify.js';
-
-export interface TransactionNode extends VoidNode {
-	nodeType: PlanNodeType.Transaction;
-	operation: 'begin' | 'commit' | 'rollback' | 'savepoint' | 'release';
-	savepoint?: string; // For ROLLBACK TO, SAVEPOINT, RELEASE
-	statementAst: AST.BeginStmt | AST.CommitStmt | AST.RollbackStmt | AST.SavepointStmt | AST.ReleaseStmt;
-}
-
-export class TransactionPlanNode extends VoidNode implements TransactionNode {
-	override readonly nodeType = PlanNodeType.Transaction;
-
-	constructor(
-		scope: Scope,
-		public readonly operation: 'begin' | 'commit' | 'rollback' | 'savepoint' | 'release',
-		public readonly statementAst: AST.BeginStmt | AST.CommitStmt | AST.RollbackStmt | AST.SavepointStmt | AST.ReleaseStmt,
-		public readonly savepoint?: string
-	) {
-		super(scope, 1); // Transaction operations have low cost
-	}
-
-	override toString(): string {
-		switch (this.operation) {
-			case 'begin':
-				return 'BEGIN';
-			case 'commit':
-				return 'COMMIT';
-			case 'rollback':
-				return this.savepoint ? `ROLLBACK TO ${this.savepoint}` : 'ROLLBACK';
-			case 'savepoint':
-				return `SAVEPOINT ${this.savepoint}`;
-			case 'release':
-				return `RELEASE ${this.savepoint}`;
-			default:
-				return `TRANSACTION ${this.operation}`;
-		}
-	}
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		const props: Record<string, unknown> = {
-			operation: this.operation,
-			statement: astToString(this.statementAst)
-		};
-
-		if (this.savepoint) {
-			props.savepoint = this.savepoint;
-		}
-
-		return props;
-	}
-}

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

@@ -1,138 +0,0 @@
-import type * as AST from '../../parser/ast.js';
-import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, isRelationalNode } from './plan-node.js';
-import { PlanNodeType } from './plan-node-type.js';
-import type { TableReferenceNode } from './reference.js';
-import type { ScalarPlanNode } from './plan-node.js';
-import type { ConflictResolution } from '../../common/constants.js';
-import type { RelationType } from '../../common/datatype.js';
-import { formatExpression } from '../../util/plan-formatter.js';
-import { buildAttributesFromFlatDescriptor } from '../../util/row-descriptor.js';
-import type { PhysicalProperties } from './plan-node.js';
-
-export interface UpdateAssignment {
-  targetColumn: AST.ColumnExpr; // Could be resolved ColumnReferenceNode or just index
-  value: ScalarPlanNode;
-}
-
-/**
- * Represents an UPDATE statement in the logical query plan.
- */
-export class UpdateNode extends PlanNode implements RelationalPlanNode {
-  override readonly nodeType = PlanNodeType.Update;
-
-  constructor(
-    scope: Scope,
-    public readonly table: TableReferenceNode,
-    public readonly assignments: ReadonlyArray<UpdateAssignment>,
-    		public readonly source: RelationalPlanNode, // Typically a FilterNode wrapping a TableReferenceNode
-		public readonly onConflict: ConflictResolution | undefined,
-    public readonly oldRowDescriptor: RowDescriptor, // For constraint checking
-    public readonly newRowDescriptor: RowDescriptor, // For constraint checking
-    public readonly flatRowDescriptor: RowDescriptor, // For flat OLD/NEW row attributes
-    public readonly mutationContextValues?: Map<string, ScalarPlanNode>, // Mutation context value expressions
-    public readonly contextAttributes?: Attribute[], // Mutation context attributes
-    public readonly contextDescriptor?: RowDescriptor, // Mutation context row descriptor
-  ) {
-    super(scope);
-  }
-
-	getType(): RelationType {
-		return this.source.getType();
-	}
-
-  getAttributes(): Attribute[] {
-    return buildAttributesFromFlatDescriptor(this.flatRowDescriptor);
-  }
-
-  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
-    // The source provides rows to be updated, table is the target of updates.
-    return [this.source, this.table];
-  }
-
-  getChildren(): readonly PlanNode[] {
-    // Return ALL child nodes: the source relation and the scalar assignment values
-    return [this.source, ...this.assignments.map(a => a.value)];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    const expectedChildCount = 1 + this.assignments.length; // source + assignment values
-    if (newChildren.length !== expectedChildCount) {
-      throw new Error(`UpdateNode expects ${expectedChildCount} children (1 source + ${this.assignments.length} assignments), got ${newChildren.length}`);
-    }
-
-    // First child is the source
-    const newSource = newChildren[0] as RelationalPlanNode;
-    if (!isRelationalNode(newSource)) {
-      throw new Error('UpdateNode: first child must be a RelationalPlanNode (source)');
-    }
-
-    // Remaining children are assignment values
-    const newAssignmentValues = newChildren.slice(1);
-    for (const child of newAssignmentValues) {
-      if (!('expression' in child)) {
-        throw new Error('UpdateNode: assignment children must be ScalarPlanNodes');
-      }
-    }
-
-    // Check if anything changed
-    const sourceChanged = newSource !== this.source;
-    const assignmentsChanged = newAssignmentValues.some((child, i) => child !== this.assignments[i].value);
-
-    if (!sourceChanged && !assignmentsChanged) {
-      return this;
-    }
-
-    // Create new assignments with updated values
-    const newAssignments = this.assignments.map((assignment, i) => ({
-      targetColumn: assignment.targetColumn,
-      value: newAssignmentValues[i] as ScalarPlanNode
-    }));
-
-    // Create new instance
-    return new UpdateNode(
-      this.scope,
-      this.table,
-      newAssignments,
-      newSource,
-      this.onConflict,
-      this.oldRowDescriptor,
-      this.newRowDescriptor,
-      this.flatRowDescriptor,
-      this.mutationContextValues,
-      this.contextAttributes,
-      this.contextDescriptor
-    );
-  }
-
-  computePhysical(): Partial<PhysicalProperties> {
-    return {
-      readonly: false,  // UPDATE has side effects
-    };
-  }
-
-  get estimatedRows(): number | undefined {
-    return this.source.estimatedRows;
-  }
-
-  override toString(): string {
-    return `UPDATE ${this.table.tableSchema.name}`;
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    const props: Record<string, unknown> = {
-      table: this.table.tableSchema.name,
-      schema: this.table.tableSchema.schemaName,
-      assignments: this.assignments.map(assign => ({
-        column: assign.targetColumn.name,
-        value: formatExpression(assign.value)
-      }))
-    };
-
-    if (this.onConflict) {
-      props.onConflict = this.onConflict;
-    }
-
-    return props;
-  }
-}