@quereus/quereus 0.2.1 → 0.4.0

package/src/planner/nodes/filter.ts

@@ -1,17 +1,19 @@
 import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode, isScalarNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode, isScalarNode, type PhysicalProperties } 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';
+import { PredicateCapable, type PredicateSourceCapable } from '../framework/characteristics.js';
+import { createTableInfoFromNode, extractConstraints } from '../analysis/constraint-extractor.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 {
+export class FilterNode extends PlanNode implements UnaryRelationalNode, PredicateCapable, PredicateSourceCapable {
 	override readonly nodeType = PlanNodeType.Filter;
 
 	constructor(
@@ -29,7 +31,7 @@ export class FilterNode extends PlanNode implements UnaryRelationalNode {
 		return this.source.getType();
 	}
 
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		// Filter preserves the same attributes as its source
 		return this.source.getAttributes();
 	}
@@ -51,6 +53,34 @@ export class FilterNode extends PlanNode implements UnaryRelationalNode {
 		return sourceRows > 0 ? Math.max(1, Math.floor(sourceRows * 0.5)) : 0;
 	}
 
+	computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+		const sourcePhysical = childrenPhysical[0];
+		const srcRows = sourcePhysical?.estimatedRows;
+		const est = this.estimatedRows;
+		let rows = (typeof srcRows === 'number' && typeof est === 'number')
+			? Math.min(srcRows, est)
+			: (srcRows ?? est);
+
+		// Attempt logical covered-key detection to infer at-most-one row
+		let uniqueKeys = sourcePhysical?.uniqueKeys;
+		const tableInfo = createTableInfoFromNode(this.source);
+		if (tableInfo.uniqueKeys && tableInfo.uniqueKeys.length > 0) {
+			const result = extractConstraints(this.predicate, [tableInfo]);
+			const covered = result.coveredKeysByTable?.get(tableInfo.relationKey) || [];
+			if (covered.length > 0) {
+				// Equality covers a unique key → at most one row
+				uniqueKeys = [[]];
+				rows = 1;
+			}
+		}
+
+		return {
+			estimatedRows: rows,
+			ordering: sourcePhysical?.ordering,
+			uniqueKeys,
+		};
+	}
+
 	override toString(): string {
 		return `WHERE ${formatExpression(this.predicate)}`;
 	}
@@ -88,4 +118,27 @@ export class FilterNode extends PlanNode implements UnaryRelationalNode {
 			newPredicate as ScalarPlanNode
 		);
 	}
+
+	// PredicateCapable interface implementation
+	getPredicate(): ScalarPlanNode | null {
+		return this.predicate;
+	}
+
+	withPredicate(newPredicate: ScalarPlanNode | null): PlanNode {
+		if (newPredicate === null) {
+			// If predicate is null, return the source directly (no filter needed)
+			return this.source;
+		}
+
+		if (newPredicate === this.predicate) {
+			return this;
+		}
+
+		return new FilterNode(this.scope, this.source, newPredicate);
+	}
+
+  // PredicateSourceCapable interface implementation
+  getPredicates(): readonly ScalarPlanNode[] {
+    return [this.predicate];
+  }
 }

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

@@ -1,120 +1,126 @@
-import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, type PhysicalProperties, isRelationalNode } 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 the source relation as a child so optimizer can traverse it
-    return [this.source];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    if (newChildren.length !== 1) {
-      throw new Error(`InsertNode expects 1 child (source), got ${newChildren.length}`);
-    }
-
-    const newSource = newChildren[0] as RelationalPlanNode;
-    if (!isRelationalNode(newSource)) {
-      throw new Error('InsertNode: child must be a RelationalPlanNode');
-    }
-
-    if (newSource === this.source) {
-      return this;
-    }
-
-    return new InsertNode(
-      this.scope,
-      this.table,
-      this.targetColumns,
-      newSource,
-      this.flatRowDescriptor
-    );
-  }
-
-  computePhysical(): Partial<PhysicalProperties> {
-    return {
-      readonly: false,  // INSERT has side effects
-    };
-  }
-
-  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;
-  }
-}
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type Attribute, type RowDescriptor, type PhysicalProperties, isRelationalNode } 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
+    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);
+  }
+
+	override getType(): RelationType {
+		return this.source.getType();
+	}
+
+  getAttributes(): readonly 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 the source relation as a child so optimizer can traverse it
+    return [this.source];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 1) {
+      throw new Error(`InsertNode expects 1 child (source), got ${newChildren.length}`);
+    }
+
+    const newSource = newChildren[0] as RelationalPlanNode;
+    if (!isRelationalNode(newSource)) {
+      throw new Error('InsertNode: child must be a RelationalPlanNode');
+    }
+
+    if (newSource === this.source) {
+      return this;
+    }
+
+    return new InsertNode(
+      this.scope,
+      this.table,
+      this.targetColumns,
+      newSource,
+      this.flatRowDescriptor,
+      this.mutationContextValues,
+      this.contextAttributes,
+      this.contextDescriptor
+    );
+  }
+
+  computePhysical(): Partial<PhysicalProperties> {
+    return {
+      readonly: false,  // INSERT has side effects
+    };
+  }
+
+  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;
+  }
+}

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

@@ -3,6 +3,7 @@ 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 { CTEScopeNode } from './cte-node.js';
 
 /**
  * Plan node for internal recursive CTE references.
@@ -10,11 +11,10 @@ import { Cached } from '../../util/cached.js';
  * Unlike CTEReferenceNode, this doesn't materialize the CTE but looks up the working table
  * from the runtime table context.
  */
-export class InternalRecursiveCTERefNode extends ZeroAryRelationalBase {
+export class InternalRecursiveCTERefNode extends ZeroAryRelationalBase implements CTEScopeNode {
 	readonly nodeType = PlanNodeType.InternalRecursiveCTERef;
 
 	private attributesCache: Cached<Attribute[]>;
-	private typeCache: Cached<RelationType>;
 
 	constructor(
 		scope: Scope,
@@ -26,12 +26,11 @@ export class InternalRecursiveCTERefNode extends ZeroAryRelationalBase {
 	) {
 		super(scope, 0.01); // Very low cost since we're just reading from working table
 		this.attributesCache = new Cached(() => this.buildAttributes());
-		this.typeCache = new Cached(() => this.buildType());
 	}
 
 	private buildAttributes(): Attribute[] {
 		// Return the attributes as provided, with proper source relation
-		return this.attributes.map((attr: any) => ({
+		return this.attributes.map((attr) => ({
 			id: attr.id,
 			name: attr.name,
 			type: attr.type,
@@ -39,26 +38,12 @@ export class InternalRecursiveCTERefNode extends ZeroAryRelationalBase {
 		}));
 	}
 
-	private buildType(): RelationType {
-		return {
-			typeClass: 'relation',
-			isReadOnly: true, // Working table is read-only from recursive case perspective
-			isSet: this.relationType.isSet,
-			columns: this.getAttributes().map((attr: any) => ({
-				name: attr.name,
-				type: attr.type
-			})),
-			keys: [],
-			rowConstraints: []
-		};
-	}
-
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		return this.attributesCache.value;
 	}
 
 	getType(): RelationType {
-		return this.typeCache.value;
+		return this.relationType;
 	}
 
 	toString(): string {

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

@@ -1,11 +1,17 @@
 import { isRelationalNode, PlanNode } from './plan-node.js';
 import type { RelationalPlanNode, Attribute, BinaryRelationalNode, ScalarPlanNode } from './plan-node.js';
 import type { RelationType } from '../../common/datatype.js';
+import type { PhysicalProperties } from './plan-node.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';
+import { JoinCapable, type PredicateSourceCapable } from '../framework/characteristics.js';
+import { normalizePredicate } from '../analysis/predicate-normalizer.js';
+import { combineJoinKeys } from '../util/key-utils.js';
+import { BinaryOpNode } from './scalar.js';
+import { ColumnReferenceNode } from './reference.js';
 
 export type JoinType = 'inner' | 'left' | 'right' | 'full' | 'cross';
 
@@ -13,7 +19,7 @@ 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 {
+export class JoinNode extends PlanNode implements BinaryRelationalNode, JoinCapable, PredicateSourceCapable {
 	readonly nodeType = PlanNodeType.Join;
 	private attributesCache: Cached<Attribute[]>;
 
@@ -23,7 +29,7 @@ export class JoinNode extends PlanNode implements BinaryRelationalNode {
 		public readonly right: RelationalPlanNode,
 		public readonly joinType: JoinType,
 		public readonly condition?: ScalarPlanNode,
-		public readonly usingColumns?: string[]
+		public readonly usingColumns?: readonly string[]
 	) {
 		// Cost estimate: base cost is sum of children plus join cost
 		const leftCost = left.getTotalCost();
@@ -38,6 +44,93 @@ export class JoinNode extends PlanNode implements BinaryRelationalNode {
 		this.attributesCache = new Cached(() => this.buildAttributes());
 	}
 
+	computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+		const leftPhys = childrenPhysical[0];
+		const rightPhys = childrenPhysical[1];
+		const leftType = this.left.getType();
+		const rightType = this.right.getType();
+		const leftAttrs = this.left.getAttributes();
+		const rightAttrs = this.right.getAttributes();
+
+		const leftIdToIndex = new Map<number, number>();
+		leftAttrs.forEach((a, i) => leftIdToIndex.set(a.id, i));
+		const rightIdToIndex = new Map<number, number>();
+		rightAttrs.forEach((a, i) => rightIdToIndex.set(a.id, i));
+
+		// Gather equi-join attribute index pairs from simple AND-of-equalities
+		const pairs: Array<{ left: number; right: number }> = [];
+		const cond = this.condition ? normalizePredicate(this.condition) : undefined;
+		const stack: ScalarPlanNode[] = [];
+		if (cond) stack.push(cond);
+		while (stack.length) {
+			const n = stack.pop()!;
+			if (n instanceof BinaryOpNode) {
+				const op = n.expression.operator;
+				if (op === 'AND') {
+					stack.push(n.left, n.right);
+					continue;
+				}
+				if (op === '=') {
+					if (n.left instanceof ColumnReferenceNode && n.right instanceof ColumnReferenceNode) {
+						let lIdx = leftIdToIndex.get(n.left.attributeId);
+						let rIdx = rightIdToIndex.get(n.right.attributeId);
+						if (lIdx !== undefined && rIdx !== undefined) {
+							pairs.push({ left: lIdx, right: rIdx });
+						} else {
+							// Try swapped alignment (right.col = left.col)
+							lIdx = leftIdToIndex.get(n.right.attributeId);
+							rIdx = rightIdToIndex.get(n.left.attributeId);
+							if (lIdx !== undefined && rIdx !== undefined) {
+								pairs.push({ left: lIdx, right: rIdx });
+							}
+						}
+					}
+				}
+			}
+		}
+
+		// Check if a logical key (RelationType.keys) is fully covered by equi-join pairs
+		function coversLogicalKey(side: 'left' | 'right'): boolean {
+			const type = side === 'left' ? leftType : rightType;
+			const eqSet = new Set<number>(pairs.map(p => side === 'left' ? p.left : p.right));
+			return type.keys.some(key => key.length > 0 && key.every(ref => eqSet.has(ref.index)));
+		}
+
+		// Check if a physical unique key (childrenPhysical.uniqueKeys) is fully covered by equi-join pairs
+		function coversPhysicalKey(side: 'left' | 'right'): boolean {
+			const phys = side === 'left' ? leftPhys : rightPhys;
+			if (!phys?.uniqueKeys) return false;
+			const eqSet = new Set<number>(pairs.map(p => side === 'left' ? p.left : p.right));
+			return phys.uniqueKeys.some(key => key.length > 0 && key.every(idx => eqSet.has(idx)));
+		}
+
+		const leftKeyCovered = coversLogicalKey('left') || coversPhysicalKey('left');
+		const rightKeyCovered = coversLogicalKey('right') || coversPhysicalKey('right');
+
+		let uniqueKeys: number[][] | undefined = undefined;
+		if (this.joinType === 'inner' || this.joinType === 'cross') {
+			const leftKeys = (leftPhys.uniqueKeys || []);
+			const rightKeys = (rightPhys.uniqueKeys || []).map(k => k.map(i => i + leftType.columns.length));
+			const preserved: number[][] = [];
+			if (rightKeyCovered) preserved.push(...leftKeys);
+			if (leftKeyCovered) preserved.push(...rightKeys);
+			if (preserved.length > 0) uniqueKeys = preserved;
+		}
+
+		let estimatedRows: number | undefined = undefined;
+		const lRows = this.left.estimatedRows;
+		const rRows = this.right.estimatedRows;
+		if (this.joinType === 'inner') {
+			if (rightKeyCovered && typeof lRows === 'number') estimatedRows = lRows;
+			if (leftKeyCovered && typeof rRows === 'number') estimatedRows = (estimatedRows === undefined) ? rRows : Math.min(estimatedRows, rRows);
+		}
+
+		return {
+			uniqueKeys,
+			estimatedRows,
+		};
+	}
+
 	private buildAttributes(): Attribute[] {
 		const leftAttrs = this.left.getAttributes();
 		const rightAttrs = this.right.getAttributes();
@@ -98,8 +191,8 @@ export class JoinNode extends PlanNode implements BinaryRelationalNode {
 		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 keys conservatively
+		const combinedKeys = combineJoinKeys(leftType.keys, rightType.keys, this.joinType, leftType.columns.length);
 
 		// Combine row constraints from both sides
 		const combinedRowConstraints = [...leftType.rowConstraints, ...rightType.rowConstraints];
@@ -210,4 +303,29 @@ export class JoinNode extends PlanNode implements BinaryRelationalNode {
 			rightRows: this.right.estimatedRows
 		};
 	}
+
+	public getJoinType(): JoinType {
+		return this.joinType;
+	}
+
+	public getJoinCondition(): ScalarPlanNode | undefined {
+		return this.condition;
+	}
+
+	public getLeftSource(): RelationalPlanNode {
+		return this.left;
+	}
+
+	public getRightSource(): RelationalPlanNode {
+		return this.right;
+	}
+
+	public getUsingColumns(): readonly string[] | undefined {
+		return this.usingColumns;
+	}
+
+	// PredicateSourceCapable: Expose ON condition (if present) as a predicate source
+	getPredicates(): readonly ScalarPlanNode[] {
+		return this.condition ? [normalizePredicate(this.condition)] : [];
+	}
 }