@quereus/quereus 0.2.1 → 0.4.5

package/src/planner/nodes/remote-query-node.ts

@@ -0,0 +1,73 @@
+import type { RelationType } from '../../common/datatype.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type UnaryRelationalNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import type { TableReferenceNode } from './reference.js';
+import type { AnyVirtualTableModule } from '../../vtab/module.js';
+import { Cached } from '../../util/cached.js';
+
+/**
+ * RemoteQueryNode represents a physical node for executing a pushed-down
+ * query pipeline in a virtual table module that supports arbitrary queries.
+ */
+export class RemoteQueryNode extends PlanNode implements UnaryRelationalNode {
+	override readonly nodeType = PlanNodeType.RemoteQuery;
+
+	private typeCache: Cached<RelationType>;
+
+	constructor(
+		scope: Scope,
+		/** The pipeline of operations the virtual table module will execute */
+		public readonly source: RelationalPlanNode,
+		/** The table reference at the leaf of the pipeline */
+		public readonly tableRef: TableReferenceNode,
+		/** Optional context data from the module's supports() assessment */
+		public readonly moduleCtx?: unknown
+	) {
+		super(scope, source.getTotalCost());
+		this.typeCache = new Cached(() => this.source.getType());
+	}
+
+	override getChildren(): readonly PlanNode[] {
+		return [this.source];
+	}
+
+	override withChildren(newChildren: readonly PlanNode[]): RemoteQueryNode {
+		if (newChildren.length !== 1) {
+			throw new Error('RemoteQueryNode requires exactly one child');
+		}
+		const newSource = newChildren[0] as RelationalPlanNode;
+		return new RemoteQueryNode(this.scope, newSource, this.tableRef, this.moduleCtx);
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getAttributes(): readonly Attribute[] {
+		return this.source.getAttributes();
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	/** Get the virtual table module for this remote query node */
+	get vtabModule(): AnyVirtualTableModule {
+		return this.tableRef.vtabModule;
+	}
+
+	override toString(): string {
+		if (this.source === this.tableRef) {
+			return `REMOTE QUERY ${this.tableRef.tableSchema.name}`;
+		}
+		return `REMOTE QUERY pipeline over ${this.tableRef.tableSchema.name}`;
+	}
+
+	getLogicalProperties(): Record<string, unknown> {
+		return {
+			table: this.tableRef.tableSchema.name,
+			moduleContext: this.moduleCtx,
+		};
+	}
+}

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

@@ -0,0 +1,86 @@
+import type { RelationType } from '../../common/datatype.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type UnaryRelationalNode, ScalarPlanNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import type { TableReferenceNode } from './reference.js';
+import type { AnyVirtualTableModule } from '../../vtab/module.js';
+import { Cached } from '../../util/cached.js';
+
+/**
+ * RetrieveNode represents the boundary between virtual table module execution and Quereus execution.
+ * It wraps a (source) pipeline of logical operators that will be pushed down to the virtual table module for execution.
+ *
+ * The pipeline always ends with a TableReferenceNode as the leaf, and may contain additional operators (Filter, Project, etc.)
+ * that the module indicated via its supports() method that it can handle.
+ */
+export class RetrieveNode extends PlanNode implements UnaryRelationalNode {
+	override readonly nodeType = PlanNodeType.Retrieve;
+
+	private typeCache: Cached<RelationType>;
+
+	constructor(
+		scope: Scope,
+		/** The pipeline of operations the virtual table module will execute */
+		public readonly source: RelationalPlanNode,
+		/** The table reference at the leaf of the pipeline */
+		public readonly tableRef: TableReferenceNode,
+		/** Optional context data from the module's supports() assessment */
+		public readonly moduleCtx?: unknown,
+		/** Captured binding expressions used by the enveloped pipeline (params/correlated) */
+		public readonly bindings?: ReadonlyArray<ScalarPlanNode>
+	) {
+		super(scope, source.getTotalCost());
+		this.typeCache = new Cached(() => this.source.getType());
+	}
+
+	override getChildren(): readonly PlanNode[] {
+		return [this.source];
+	}
+
+	override withChildren(newChildren: readonly PlanNode[]): RetrieveNode {
+		if (newChildren.length !== 1) {
+			throw new Error('RetrieveNode requires exactly one child');
+		}
+		const newSource = newChildren[0] as RelationalPlanNode;
+		return new RetrieveNode(this.scope, newSource, this.tableRef, this.moduleCtx, this.bindings);
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getAttributes(): readonly Attribute[] {
+		return this.source.getAttributes();
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	/** Get the virtual table module for this retrieve node */
+	get vtabModule(): AnyVirtualTableModule {
+		return this.tableRef.vtabModule;
+	}
+
+	/** Create a new RetrieveNode with updated source pipeline and module context */
+	withPipeline(newSource: RelationalPlanNode, newModuleCtx?: unknown, newBindings?: ReadonlyArray<ScalarPlanNode>): RetrieveNode {
+		return new RetrieveNode(this.scope, newSource, this.tableRef, newModuleCtx, newBindings ?? this.bindings);
+	}
+
+	override toString(): string {
+		if (this.source === this.tableRef) {
+			return `RETRIEVE ${this.tableRef.tableSchema.name}`;
+		}
+		return `RETRIEVE pipeline over ${this.tableRef.tableSchema.name}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		const bindingNodeTypes = (this.bindings ?? []).map(b => b.nodeType);
+		return {
+			table: this.tableRef.tableSchema.name,
+			moduleContext: this.moduleCtx,
+			bindingsCount: bindingNodeTypes.length,
+			bindingsNodeTypes: bindingNodeTypes,
+		};
+	}
+}

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

@@ -1,11 +1,12 @@
 import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, isRelationalNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, isRelationalNode, type PhysicalProperties } from './plan-node.js';
 import { PlanNodeType } from './plan-node-type.js';
 import type { ScalarPlanNode } from './plan-node.js';
 import type { RelationType } from '../../common/datatype.js';
 import { ColumnReferenceNode } from './reference.js';
 import { expressionToString } from '../../util/ast-stringify.js';
 import { Cached } from '../../util/cached.js';
+import { projectKeys } from '../util/key-utils.js';
 
 export interface ReturningProjection {
   node: ScalarPlanNode;
@@ -22,14 +23,14 @@ export class ReturningNode extends PlanNode implements RelationalPlanNode {
   override readonly nodeType = PlanNodeType.Returning;
 
   private outputTypeCache: Cached<RelationType>;
-  private attributesCache: Cached<Attribute[]>;
+  private attributesCache: Cached<readonly Attribute[]>;
 
   constructor(
     scope: Scope,
     public readonly executor: RelationalPlanNode, // The DML operation that yields affected rows
     public readonly projections: ReadonlyArray<ReturningProjection>,
     /** Optional predefined attributes for preserving IDs during optimization */
-    predefinedAttributes?: Attribute[]
+    predefinedAttributes?: readonly Attribute[]
   ) {
     super(scope);
 
@@ -90,17 +91,28 @@ export class ReturningNode extends PlanNode implements RelationalPlanNode {
       };
     });
 
+    // Logical key propagation via simple column references
+    const execType = this.executor.getType();
+    const execAttrs = this.executor.getAttributes();
+    const srcToOut = new Map<number, number>();
+    this.projections.forEach((proj, outIdx) => {
+      if (proj.node instanceof ColumnReferenceNode) {
+        const srcIndex = execAttrs.findIndex(a => a.id === (proj.node as ColumnReferenceNode).attributeId);
+        if (srcIndex >= 0) srcToOut.set(srcIndex, outIdx);
+      }
+    });
+
     return {
       typeClass: 'relation',
       columns,
-      isSet: this.executor.getType().isSet, // Preserve set/bag semantics
+      isSet: execType.isSet,
       isReadOnly: false,
-      keys: [], // No known keys for returning results
-      rowConstraints: [], // No row constraints for returning results
+      keys: projectKeys(execType.keys, srcToOut),
+      rowConstraints: [],
     };
   }
 
-  private buildAttributes(): Attribute[] {
+  private buildAttributes(): readonly Attribute[] {
     // Create attributes for the projected columns
     // Get the computed column names from the type
     const outputType = this.getType();
@@ -141,9 +153,9 @@ export class ReturningNode extends PlanNode implements RelationalPlanNode {
     return this.outputTypeCache.value;
   }
 
-  getAttributes(): Attribute[] {
-    return this.attributesCache.value;
-  }
+  getAttributes(): readonly Attribute[] {
+		return this.attributesCache.value;
+	}
 
   getRelations(): readonly RelationalPlanNode[] {
     // Return the executor which is now a RelationalPlanNode
@@ -207,6 +219,36 @@ export class ReturningNode extends PlanNode implements RelationalPlanNode {
     return this.executor.estimatedRows;
   }
 
+  computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+    const sourcePhysical = childrenPhysical[0];
+    const execAttrs = this.executor.getAttributes();
+    const map = new Map<number, number>();
+    this.projections.forEach((proj, outIdx) => {
+      if (proj.node instanceof ColumnReferenceNode) {
+        const srcIndex = execAttrs.findIndex(a => a.id === (proj.node as ColumnReferenceNode).attributeId);
+        if (srcIndex >= 0) map.set(srcIndex, outIdx);
+      }
+    });
+
+    const uniqueKeys = (sourcePhysical?.uniqueKeys || [])
+      .map(key => {
+        const projected: number[] = [];
+        for (const col of key) {
+          const outIdx = map.get(col);
+          if (outIdx === undefined) return null;
+          projected.push(outIdx);
+        }
+        return projected;
+      })
+      .filter((k): k is number[] => k !== null);
+
+    return {
+      estimatedRows: this.estimatedRows,
+      ordering: sourcePhysical?.ordering,
+      uniqueKeys,
+    };
+  }
+
   override toString(): string {
     const projList = this.projections.length > 3
       ? `${this.projections.length} columns`

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

@@ -50,7 +50,7 @@ export class SequencingNode extends PlanNode implements UnaryRelationalNode {
 				columns: [...sourceType.columns, sequenceColumn],
 				keys: [allColumnsKey], // All columns including sequence form a unique key
 				rowConstraints: sourceType.rowConstraints,
-			} as RelationType;
+			} satisfies RelationType;
 		});
 	}
 
@@ -58,7 +58,7 @@ export class SequencingNode extends PlanNode implements UnaryRelationalNode {
 		return this.outputTypeCache.value;
 	}
 
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		// Sort preserves the same attributes as its source
 		return this.source.getAttributes();
 	}

package/src/planner/nodes/set-operation-node.ts

@@ -9,7 +9,7 @@ import { StatusCode } from '../../common/types.js';
 
 export class SetOperationNode extends PlanNode implements BinaryRelationalNode {
   readonly nodeType = PlanNodeType.SetOperation;
-  private attributesCache: Cached<Attribute[]>;
+  private attributesCache: Cached<readonly Attribute[]>;
 
   constructor(
     scope: Scope,
@@ -28,14 +28,14 @@ export class SetOperationNode extends PlanNode implements BinaryRelationalNode {
     this.attributesCache = new Cached(() => this.buildAttributes());
   }
 
-  private buildAttributes(): Attribute[] {
+  private buildAttributes(): readonly Attribute[] {
     const leftAttrs = this.left.getAttributes();
     // Preserve left child's attributes directly to avoid any mapping issues
     // This ensures ORDER BY expressions can resolve to the same attribute IDs
     return leftAttrs;
   }
 
-  getAttributes(): Attribute[] {
+  getAttributes(): readonly Attribute[] {
     return this.attributesCache.value;
   }
 

package/src/planner/nodes/sort.ts

@@ -6,6 +6,7 @@ import { formatSortKey } from '../../util/plan-formatter.js';
 import { quereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
 import { extractOrderingFromSortKeys } from '../framework/physical-utils.js';
+import { SortCapable } from '../framework/characteristics.js';
 
 /**
  * Represents a sort key for ordering results
@@ -25,7 +26,7 @@ export interface SortKey {
  * and outputs rows sorted according to the keys.
  * This is a physical operation that materializes and sorts rows.
  */
-export class SortNode extends PlanNode implements UnaryRelationalNode {
+export class SortNode extends PlanNode implements UnaryRelationalNode, SortCapable {
 	override readonly nodeType = PlanNodeType.Sort;
 
 	constructor(
@@ -48,7 +49,7 @@ export class SortNode extends PlanNode implements UnaryRelationalNode {
 		return this.source.getType();
 	}
 
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		// Sort preserves the same attributes as its source
 		return this.source.getAttributes();
 	}
@@ -76,9 +77,7 @@ export class SortNode extends PlanNode implements UnaryRelationalNode {
 
 		return {
 			estimatedRows: this.estimatedRows,
-			// Only set ordering if we can extract it from trivial column references
 			ordering,
-			// Preserve unique keys from source
 			uniqueKeys: sourcePhysical?.uniqueKeys,
 		};
 	}
@@ -134,4 +133,34 @@ export class SortNode extends PlanNode implements UnaryRelationalNode {
 			newSortKeys
 		);
 	}
+
+	// SortCapable interface implementation
+	getSortKeys(): readonly { expression: ScalarPlanNode; direction: 'asc' | 'desc' }[] {
+		return this.sortKeys.map(key => ({
+			expression: key.expression,
+			direction: key.direction
+		}));
+	}
+
+	withSortKeys(keys: readonly { expression: ScalarPlanNode; direction: 'asc' | 'desc' }[]): PlanNode {
+		// Convert to internal SortKey format with nulls handling
+		const newSortKeys = keys.map(key => ({
+			expression: key.expression,
+			direction: key.direction,
+			nulls: undefined as 'first' | 'last' | undefined
+		}));
+
+		// Check if anything changed
+		const changed = newSortKeys.length !== this.sortKeys.length ||
+			newSortKeys.some((key, i) =>
+				key.expression !== this.sortKeys[i].expression ||
+				key.direction !== this.sortKeys[i].direction
+			);
+
+		if (!changed) {
+			return this;
+		}
+
+		return new SortNode(this.scope, this.source, newSortKeys);
+	}
 }

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

@@ -6,6 +6,7 @@ import { Cached } from '../../util/cached.js';
 import { formatExpressionList } from '../../util/plan-formatter.js';
 import { quereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
+import type { ColumnReferenceNode } from './reference.js';
 
 /**
  * Physical node representing a streaming aggregate operation.
@@ -86,7 +87,7 @@ export class StreamAggregateNode extends PlanNode implements UnaryRelationalNode
   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
+      const colRef = expr as ColumnReferenceNode;
       return colRef.expression.name;
     }
     // Otherwise, use a generic name
@@ -243,6 +244,9 @@ export class StreamAggregateNode extends PlanNode implements UnaryRelationalNode
       }));
     }
 
+    // Expose logical unique keys: group-by columns (0..groupCount-1) or [[]] for global aggregate
+    const groupCount = this.groupBy.length;
+    (props as any).uniqueKeys = groupCount > 0 ? [Array.from({ length: groupCount }, (_, i) => i)] : [[]];
     return props;
   }
 

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

@@ -11,12 +11,13 @@ 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 {
+export abstract class TableAccessNode extends PlanNode implements UnaryRelationalNode, TableAccessCapable {
 	private attributesCache: Cached<Attribute[]>;
 	private outputType: Cached<RelationType>;
 
@@ -48,6 +49,13 @@ export abstract class TableAccessNode extends PlanNode implements UnaryRelationa
 		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}`);
@@ -73,7 +81,7 @@ export abstract class TableAccessNode extends PlanNode implements UnaryRelationa
 		return {
 			table: this.source.tableSchema.name,
 			schema: this.source.tableSchema.schemaName,
-			accessMethod: this.nodeType,
+			accessMethod: this.getAccessMethod(),
 			filterInfo: {
 				usableIndex: this.filterInfo.indexInfoOutput.idxStr,
 				matchedClauses: this.filterInfo.indexInfoOutput.aConstraintUsage?.length || 0,
@@ -91,6 +99,10 @@ export abstract class TableAccessNode extends PlanNode implements UnaryRelationa
 export class SeqScanNode extends TableAccessNode {
 	override readonly nodeType = PlanNodeType.SeqScan;
 
+	getAccessMethod(): 'sequential' {
+		return 'sequential';
+	}
+
 	computePhysical(): Partial<PhysicalProperties> {
 		return {
 			estimatedRows: this.source.estimatedRows,
@@ -148,6 +160,10 @@ export class IndexScanNode extends TableAccessNode {
 		super(scope, source, filterInfo, estimatedCostOverride);
 	}
 
+	getAccessMethod(): 'index-scan' {
+		return 'index-scan';
+	}
+
 	computePhysical(): Partial<PhysicalProperties> {
 		return {
 			estimatedRows: this.source.estimatedRows,
@@ -220,14 +236,23 @@ export class IndexSeekNode extends TableAccessNode {
 		super(scope, source, filterInfo, estimatedCostOverride);
 	}
 
+	getAccessMethod(): 'index-seek' {
+		return 'index-seek';
+	}
+
 	computePhysical(): Partial<PhysicalProperties> {
-		return {
+		const base = {
 			uniqueKeys: this.source.getType().keys.map(key => key.map(colRef => colRef.index)),
-			// Index seeks can provide ordering and usually return few rows
 			ordering: this.providesOrdering,
-			// Seeks typically return much fewer rows than estimated
 			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 {