@quereus/quereus 0.1.0

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

@@ -0,0 +1,72 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableReferenceNode } from './reference.js';
+import type { RelationType } from '../../common/datatype.js';
+import { buildAttributesFromFlatDescriptor } from '../../util/row-descriptor.js';
+
+/**
+ * Represents a DELETE statement in the logical query plan.
+ */
+export class DeleteNode extends PlanNode implements RelationalPlanNode {
+  override readonly nodeType = PlanNodeType.Delete;
+
+  constructor(
+    scope: Scope,
+    public readonly table: TableReferenceNode,
+    public readonly source: RelationalPlanNode, // Typically a FilterNode wrapping a TableScanNode
+    public readonly oldRowDescriptor?: RowDescriptor, // For constraint checking
+    public readonly flatRowDescriptor?: RowDescriptor,
+  ) {
+    super(scope);
+  }
+
+	getType(): RelationType {
+		return this.source.getType();
+	}
+
+  getAttributes(): Attribute[] {
+    if (this.flatRowDescriptor && Object.keys(this.flatRowDescriptor).length > 0) {
+      return buildAttributesFromFlatDescriptor(this.flatRowDescriptor);
+    }
+    // Fallback to source attributes for backward compatibility
+    return this.source.getAttributes();
+  }
+
+  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
+    // The source provides keys to be deleted, table is the target of deletions.
+    return [this.source, this.table];
+  }
+
+  getChildren(): readonly [] {
+    return [];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 0) {
+      throw new Error(`DeleteNode expects 0 children, got ${newChildren.length}`);
+    }
+    return this; // No children in getChildren(), source is accessed via getRelations()
+  }
+
+  get estimatedRows(): number | undefined {
+    return this.source.estimatedRows;
+  }
+
+  override toString(): string {
+    return `DELETE FROM ${this.table.tableSchema.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName
+    };
+
+    if (this.flatRowDescriptor) {
+      props.hasFlatRowDescriptor = true;
+    }
+
+    return props;
+  }
+}

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

@@ -0,0 +1,93 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type Attribute } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import { quereusError } from '../../common/errors.js';
+import { StatusCode } from '../../index.js';
+
+/**
+ * Represents a DISTINCT operation that eliminates duplicate rows.
+ * It takes an input relation and outputs unique rows.
+ */
+export class DistinctNode extends PlanNode implements UnaryRelationalNode {
+  override readonly nodeType = PlanNodeType.Distinct;
+
+  constructor(
+    scope: Scope,
+    public readonly source: RelationalPlanNode,
+    estimatedCostOverride?: number
+  ) {
+    // Cost: cost of source + cost of deduplication (roughly O(n log n) for sorting approach)
+    const sourceCost = source.getTotalCost();
+    const sourceRows = source.estimatedRows ?? 1;
+    const deduplicationCost = sourceRows * Math.log2(Math.max(1, sourceRows));
+    super(scope, estimatedCostOverride ?? (sourceCost + deduplicationCost));
+  }
+
+  getType(): RelationType {
+    // DISTINCT always produces a set (no duplicates)
+    const sourceType = this.source.getType();
+    return {
+      ...sourceType,
+			// TODO: ensure that formed key is represented in the type
+      isSet: true // DISTINCT guarantees uniqueness
+    };
+  }
+
+  getAttributes(): Attribute[] {
+    // DISTINCT preserves the same attributes as its source
+    return this.source.getAttributes();
+  }
+
+  getChildren(): readonly [RelationalPlanNode] {
+    return [this.source];
+  }
+
+  getRelations(): readonly [RelationalPlanNode] {
+    return [this.source];
+  }
+
+  get estimatedRows(): number | undefined {
+    // DISTINCT reduces the number of rows by eliminating duplicates
+    // This is a rough estimate - in reality it depends on data distribution
+    const sourceRows = this.source.estimatedRows;
+    if (sourceRows === undefined) return undefined;
+    if (sourceRows <= 1) return sourceRows;
+
+    // Rough heuristic: assume some duplicates exist
+    // More sophisticated planners would use column statistics
+    return Math.max(1, Math.floor(sourceRows * 0.7));
+  }
+
+  override toString(): string {
+    return 'DISTINCT';
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return { };
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 1) {
+      quereusError(`DistinctNode expects 1 child, got ${newChildren.length}`, StatusCode.INTERNAL);
+    }
+
+    const [newSource] = newChildren;
+
+    // Type check
+    if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+      quereusError('DistinctNode: child must be a RelationalPlanNode', StatusCode.INTERNAL);
+    }
+
+    // Return same instance if nothing changed
+    if (newSource === this.source) {
+      return this;
+    }
+
+    // Create new instance preserving attributes (distinct preserves source attributes)
+    return new DistinctNode(
+      this.scope,
+      newSource as RelationalPlanNode
+    );
+  }
+}

package/src/planner/nodes/dml-executor-node.ts

@@ -0,0 +1,98 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type PhysicalProperties } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableReferenceNode } from './reference.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { ConflictResolution } from '../../common/constants.js';
+import { RowOp } from '../../parser/ast.js';
+
+/**
+ * Executes actual database insert/update/delete operations after constraint validation.
+ * This node performs the actual vtab.xUpdate operations and yields the affected rows.
+ * All data transformations (defaults, conversions, etc.) happen before this node.
+ */
+export class DmlExecutorNode extends PlanNode implements RelationalPlanNode {
+  override readonly nodeType = PlanNodeType.UpdateExecutor;
+
+  constructor(
+    scope: Scope,
+    public readonly source: RelationalPlanNode,
+    public readonly table: TableReferenceNode,
+    public readonly operation: RowOp,
+    public readonly onConflict?: ConflictResolution, // Used for INSERT operations
+  ) {
+    super(scope);
+  }
+
+  getType(): RelationType {
+    return this.source.getType();
+  }
+
+  getAttributes(): Attribute[] {
+    return this.source.getAttributes();
+  }
+
+  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
+    return [this.source, this.table];
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [this.source];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 1) {
+      throw new Error(`UpdateExecutorNode expects 1 child, got ${newChildren.length}`);
+    }
+
+    const [newSource] = newChildren;
+
+    // Type check
+    if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+      throw new Error('UpdateExecutorNode: child must be a RelationalPlanNode');
+    }
+
+    // Return same instance if nothing changed
+    if (newSource === this.source) {
+      return this;
+    }
+
+    // Create new instance
+    return new DmlExecutorNode(
+      this.scope,
+      newSource as RelationalPlanNode,
+      this.table,
+      this.operation,
+      this.onConflict
+    );
+  }
+
+  get estimatedRows(): number | undefined {
+    return this.source.estimatedRows;
+  }
+
+  override toString(): string {
+    return `EXECUTE ${this.operation} ${this.table.tableSchema.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {
+      operation: this.operation,
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName,
+    };
+
+    if (this.onConflict) {
+      props.onConflict = this.onConflict;
+    }
+
+    return props;
+  }
+
+  computePhysical(): Partial<PhysicalProperties> {
+    return {
+      readonly: false, // DML executor has side effects
+      idempotent: false, // DML operations are generally not idempotent
+    };
+  }
+}

package/src/planner/nodes/drop-table-node.ts

@@ -0,0 +1,31 @@
+import type { Scope } from '../scopes/scope.js';
+import { VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type * as AST from '../../parser/ast.js';
+import { expressionToString } from '../../util/ast-stringify.js';
+
+/**
+ * Represents a DROP TABLE statement in the logical query plan.
+ */
+export class DropTableNode extends VoidNode {
+  override readonly nodeType = PlanNodeType.DropTable;
+
+  constructor(
+    scope: Scope,
+    public readonly statementAst: AST.DropStmt,
+  ) {
+    super(scope);
+  }
+
+  override toString(): string {
+    return `DROP TABLE ${this.statementAst.name.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      table: this.statementAst.name.name,
+      schema: this.statementAst.name.schema,
+      statement: expressionToString(this.statementAst as any)
+    };
+  }
+}

package/src/planner/nodes/drop-view-node.ts

@@ -0,0 +1,33 @@
+import { VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+
+/**
+ * Plan node for DROP VIEW statements.
+ * Removes a view definition from the schema.
+ */
+export class DropViewNode extends VoidNode {
+	readonly nodeType = PlanNodeType.DropView;
+
+	constructor(
+		scope: Scope,
+		public readonly viewName: string,
+		public readonly schemaName: string,
+		public readonly ifExists: boolean
+	) {
+		super(scope, 1); // Low cost for DDL operations
+	}
+
+	override toString(): string {
+		const ifExistsClause = this.ifExists ? 'IF EXISTS ' : '';
+		return `DROP VIEW ${ifExistsClause}${this.schemaName}.${this.viewName}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			viewName: this.viewName,
+			schemaName: this.schemaName,
+			ifExists: this.ifExists
+		};
+	}
+}

package/src/planner/nodes/filter.ts

@@ -0,0 +1,91 @@
+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 { formatExpression } from '../../util/plan-formatter.js';
+import { quereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+/**
+ * Represents a filter operation (WHERE clause).
+ * It takes an input relation and a predicate expression,
+ * and outputs rows for which the predicate is true.
+ */
+export class FilterNode extends PlanNode implements UnaryRelationalNode {
+	override readonly nodeType = PlanNodeType.Filter;
+
+	constructor(
+		scope: Scope,
+		public readonly source: RelationalPlanNode,
+		public readonly predicate: ScalarPlanNode,
+		estimatedCostOverride?: number
+	) {
+		// Cost: cost of source + cost of evaluating predicate for each source row
+		super(scope, estimatedCostOverride ?? (source.getTotalCost() + (source.estimatedRows ?? 1) * predicate.getTotalCost()));
+	}
+
+	getType(): RelationType {
+		// Filter preserves the type of the source relation
+		return this.source.getType();
+	}
+
+	getAttributes(): Attribute[] {
+		// Filter preserves the same attributes as its source
+		return this.source.getAttributes();
+	}
+
+	getChildren(): readonly [RelationalPlanNode, ScalarPlanNode] {
+		return [this.source, this.predicate];
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	get estimatedRows(): number | undefined {
+		// This is a rough estimate. A more sophisticated planner would use selectivity estimates.
+		// For now, assume a selectivity of 0.5 if source has rows, otherwise 0.
+		// TODO: Use selectivity estimates
+		const sourceRows = this.source.estimatedRows;
+		if (sourceRows === undefined) return undefined;
+		return sourceRows > 0 ? Math.max(1, Math.floor(sourceRows * 0.5)) : 0;
+	}
+
+	override toString(): string {
+		return `WHERE ${formatExpression(this.predicate)}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			predicate: formatExpression(this.predicate)
+		};
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 2) {
+			quereusError(`FilterNode expects 2 children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+
+		const [newSource, newPredicate] = newChildren;
+
+		// Type check
+		if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+			quereusError('FilterNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+		if (!('expression' in newPredicate)) {
+			quereusError('FilterNode: second child must be a ScalarPlanNode', StatusCode.INTERNAL);
+		}
+
+		// Return same instance if nothing changed
+		if (newSource === this.source && newPredicate === this.predicate) {
+			return this;
+		}
+
+		// Create new instance preserving attributes (filter preserves source attributes)
+		return new FilterNode(
+			this.scope,
+			newSource as RelationalPlanNode,
+			newPredicate as ScalarPlanNode
+		);
+	}
+}

package/src/planner/nodes/function.ts

@@ -0,0 +1,93 @@
+import type { ScalarType } from '../../common/datatype.js';
+import type * as AST from '../../parser/ast.js';
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type NaryScalarNode, type ScalarPlanNode, type PhysicalProperties } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import { formatExpressionList, formatScalarType } from '../../util/plan-formatter.js';
+import type { FunctionSchema } from '../../schema/function.js';
+import { FunctionFlags } from '../../common/constants.js';
+
+export class ScalarFunctionCallNode extends PlanNode implements NaryScalarNode {
+	override readonly nodeType = PlanNodeType.ScalarFunctionCall;
+
+	constructor(
+		scope: Scope,
+		public readonly expression: AST.FunctionExpr,
+		public readonly functionSchema: FunctionSchema,
+		public readonly operands: ScalarPlanNode[]
+	) {
+		super(scope);
+	}
+
+	getType(): ScalarType {
+		return this.functionSchema.returnType as ScalarType;
+	}
+
+	getChildren(): readonly ScalarPlanNode[] {
+		return this.operands;
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== this.operands.length) {
+			throw new Error(`ScalarFunctionCallNode expects ${this.operands.length} children, got ${newChildren.length}`);
+		}
+
+		// Type check
+		for (const child of newChildren) {
+			if (!('expression' in child)) {
+				throw new Error('ScalarFunctionCallNode: 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 ScalarFunctionCallNode(
+			this.scope,
+			this.expression,
+			this.functionSchema,
+			newChildren as ScalarPlanNode[]
+		);
+	}
+
+	override toString(): string {
+		return `${this.expression.name}(${formatExpressionList(this.operands)})`;
+	}
+
+	override computePhysical(_childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+		// Function calls derive properties from their arguments and the function itself
+		const result: Partial<PhysicalProperties> = {};
+
+		// Use function schema to determine deterministic and readonly properties
+		const functionIsDeterministic = (this.functionSchema.flags & FunctionFlags.DETERMINISTIC) !== 0;
+		const functionIsReadonly = (this.functionSchema.returnType as ScalarType).isReadOnly ?? true;
+
+		// Function is deterministic only if both function and all arguments are deterministic
+		if (!functionIsDeterministic) {
+			result.deterministic = false;
+		}
+
+		// Function is readonly only if both function and all arguments are readonly
+		if (!functionIsReadonly) {
+			result.readonly = false;
+		}
+
+		return result;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			function: this.expression.name,
+			arguments: this.operands.map(op => op.toString()),
+			resultType: formatScalarType(this.functionSchema.returnType as ScalarType)
+		};
+	}
+}

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

@@ -0,0 +1,97 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableReferenceNode } from './reference.js';
+import type { ColumnDef, RelationType } from '../../common/datatype.js';
+
+/**
+ * Represents an INSERT statement in the logical query plan.
+ * RelationalPlanNode because this node may be a return value of a SELECT node.
+ */
+export class InsertNode extends PlanNode implements RelationalPlanNode {
+  override readonly nodeType = PlanNodeType.Insert;
+
+  constructor(
+    scope: Scope,
+    public readonly table: TableReferenceNode,
+    public readonly targetColumns: ColumnDef[],
+    public readonly source: RelationalPlanNode, // Could be ValuesNode or output of a SELECT
+    public readonly flatRowDescriptor?: RowDescriptor, // For flat OLD/NEW row output
+  ) {
+    super(scope);
+  }
+
+	override getType(): RelationType {
+		return this.source.getType();
+	}
+
+  getAttributes(): Attribute[] {
+    // If we have a flatRowDescriptor, produce attributes that correspond to the flat OLD/NEW row structure
+    if (this.flatRowDescriptor && Object.keys(this.flatRowDescriptor).length > 0) {
+      // Create attributes for the flat row: OLD columns first, then NEW columns
+      const attributes: Attribute[] = [];
+
+      // Add attributes for each position in the flat row
+      for (const attrIdStr in this.flatRowDescriptor) {
+        const attrId = parseInt(attrIdStr);
+        const flatIndex = this.flatRowDescriptor[attrId];
+
+        // Determine if this is OLD or NEW based on index
+        const tableColumnCount = this.table.tableSchema.columns.length;
+        const isOld = flatIndex < tableColumnCount;
+        const columnIndex = isOld ? flatIndex : flatIndex - tableColumnCount;
+        const col = this.table.tableSchema.columns[columnIndex];
+
+        attributes[flatIndex] = {
+          id: attrId,
+          name: col.name,
+          type: {
+            typeClass: 'scalar',
+            affinity: col.affinity,
+            nullable: isOld ? true : !col.notNull, // OLD values can be null, NEW follows column constraints
+            isReadOnly: false
+          },
+          sourceRelation: `${isOld ? 'OLD' : 'NEW'}.${this.table.tableSchema.name}`
+        };
+      }
+
+      return attributes;
+    }
+
+    // INSERT produces the same attributes as its source (for non-RETURNING cases)
+    return this.source.getAttributes();
+  }
+
+  override getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
+    return [this.source, this.table];
+  }
+
+  override getChildren(): readonly PlanNode[] {
+    return [];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 0) {
+      throw new Error(`InsertNode expects 0 children, got ${newChildren.length}`);
+    }
+    return this; // No children in getChildren(), source is accessed via getRelations()
+  }
+
+  override toString(): string {
+    return `INSERT INTO ${this.table.tableSchema.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName,
+      targetColumns: this.targetColumns.map(col => col.name)
+    };
+
+    if (this.flatRowDescriptor) {
+      props.hasFlatRowDescriptor = true;
+    }
+
+    return props;
+  }
+}