@quereus/quereus 0.7.2 → 0.7.4

package/src/planner/nodes/reference.ts

@@ -1,334 +0,0 @@
-import type { BaseType, ScalarType, RelationType } from '../../common/datatype.js';
-import { PlanNode, type ZeroAryRelationalNode, type ZeroAryScalarNode, type Attribute } from './plan-node.js';
-import { PlanNodeType } from './plan-node-type.js';
-import type { TableSchema } from '../../schema/table.js';
-import type { Scope } from '../scopes/scope.js';
-import type * as AST from '../../parser/ast.js';
-import { relationTypeFromTableSchema } from '../type-utils.js';
-import { Cached } from '../../util/cached.js';
-import type { FunctionSchema } from '../../schema/function.js';
-import { isTableValuedFunctionSchema } from '../../schema/function.js';
-import { formatScalarType } from '../../util/plan-formatter.js';
-import { quereusError } from '../../common/errors.js';
-import { StatusCode } from '../../common/types.js';
-import type { AnyVirtualTableModule } from '../../vtab/module.js';
-import type { ColumnBindingProvider } from '../framework/characteristics.js';
-import type { TableAccessCapable } from '../framework/characteristics.js';
-
-/** Represents a reference to a table in the global schema. */
-export class TableReferenceNode extends PlanNode implements ZeroAryRelationalNode, TableAccessCapable, ColumnBindingProvider {
-	override readonly nodeType = PlanNodeType.TableReference;
-
-	private typeCache: Cached<RelationType>;
-	private attributesCache: Cached<Attribute[]>;
-
-	constructor(
-		scope: Scope,
-		public readonly tableSchema: TableSchema,
-		public readonly vtabModule: AnyVirtualTableModule,
-		public readonly vtabAuxData?: unknown,
-		estimatedCostOverride?: number
-	) {
-		super(scope, estimatedCostOverride ?? 1);
-		this.typeCache = new Cached(() => relationTypeFromTableSchema(tableSchema));
-		this.attributesCache = new Cached(() => {
-			// Create attributes from table schema columns
-			return this.tableSchema.columns.map((column) => ({
-				id: PlanNode.nextAttrId(),
-				name: column.name,
-				type: {
-					typeClass: 'scalar' as const,
-					logicalType: column.logicalType,
-					nullable: !column.notNull,
-					isReadOnly: false,
-					collationName: column.collation
-				},
-				sourceRelation: `${this.tableSchema.schemaName}.${this.tableSchema.name}`,
-				relationName: this.tableSchema.name
-			}));
-		});
-	}
-
-	getType(): RelationType {
-		return this.typeCache.value;
-	}
-
-	getAttributes(): Attribute[] {
-		return this.attributesCache.value;
-	}
-
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	getRelations(): readonly [] {
-		return [];
-	}
-
-	withChildren(newChildren: readonly PlanNode[]): PlanNode {
-		if (newChildren.length !== 0) {
-			quereusError(`TableReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
-		}
-		return this; // No children, so no change
-	}
-
-	get estimatedRows(): number | undefined {
-		return this.tableSchema.estimatedRows;
-	}
-
-	override toString(): string {
-		return `${this.tableSchema.schemaName}.${this.tableSchema.name}`;
-	}
-
-	getAccessMethod(): 'sequential' | 'index-scan' | 'index-seek' | 'virtual' {
-		// Logical table reference - will be converted to physical by optimizer
-		return 'virtual';
-	}
-
-  // ColumnBindingProvider implementation
-  getBindingRelationName(): string {
-    return `${this.tableSchema.schemaName}.${this.tableSchema.name}`;
-  }
-
-  getBindingAttributes(): ReadonlyArray<{ id: number; name: string }> {
-    return this.getAttributes().map(a => ({ id: a.id, name: a.name }));
-  }
-
-  getColumnIndexForAttribute(attributeId: number): number | undefined {
-    const attrs = this.getAttributes();
-    const idx = attrs.findIndex(a => a.id === attributeId);
-    return idx >= 0 ? idx : undefined;
-  }
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		return {
-			schema: this.tableSchema.schemaName,
-			table: this.tableSchema.name,
-			columns: this.tableSchema.columns.map(col => col.name),
-			estimates: {
-				rows: this.tableSchema.estimatedRows
-			}
-		};
-	}
-}
-
-export class TableFunctionReferenceNode extends PlanNode implements ZeroAryRelationalNode {
-	override readonly nodeType = PlanNodeType.TableFunctionReference;
-
-	private attributesCache: Cached<Attribute[]>;
-
-	constructor(
-		scope: Scope,
-		public readonly functionSchema: FunctionSchema,
-		estimatedCostOverride?: number
-	) {
-		super(scope, estimatedCostOverride ?? 1);
-
-		this.attributesCache = new Cached(() => {
-			// Create attributes from function schema return type
-			if (isTableValuedFunctionSchema(this.functionSchema)) {
-				return this.functionSchema.returnType.columns.map((column) => ({
-					id: PlanNode.nextAttrId(),
-					name: column.name,
-					type: column.type,
-					sourceRelation: `${this.functionSchema.name}()`,
-					relationName: this.functionSchema.name
-				}));
-			}
-			return [];
-		});
-	}
-
-	getType(): RelationType {
-		if (isTableValuedFunctionSchema(this.functionSchema)) {
-			return this.functionSchema.returnType;
-		}
-		quereusError(
-			`Function ${this.functionSchema.name} is not a table-valued function`,
-			StatusCode.INTERNAL
-		);
-	}
-
-	getAttributes(): Attribute[] {
-		return this.attributesCache.value;
-	}
-
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	getRelations(): readonly [] {
-		return [];
-	}
-
-	withChildren(newChildren: readonly PlanNode[]): PlanNode {
-		if (newChildren.length !== 0) {
-			quereusError(`TableFunctionReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
-		}
-		return this; // No children, so no change
-	}
-
-	get estimatedRows(): number | undefined {
-		return 100; // Default estimate for table functions
-	}
-
-	override toString(): string {
-		return `${this.functionSchema.name}()`;
-	}
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		const props: Record<string, unknown> = {
-			function: this.functionSchema.name,
-			numArgs: this.functionSchema.numArgs
-		};
-
-		if (isTableValuedFunctionSchema(this.functionSchema)) {
-			props.columns = this.functionSchema.returnType.columns.map(col => col.name);
-		}
-
-		return props;
-	}
-}
-
-/**
- * Represents a reference to a column from a relational node.
- * Uses attribute IDs for stable references across plan transformations.
- */
-export class ColumnReferenceNode extends PlanNode implements ZeroAryScalarNode {
-	override readonly nodeType = PlanNodeType.ColumnReference;
-
-	constructor(
-		scope: Scope,
-		public readonly expression: AST.ColumnExpr, // Original AST expression for this reference
-		public readonly columnType: ScalarType,
-		public readonly attributeId: number, // Stable attribute ID instead of node reference
-		public readonly columnIndex: number, // Position in the row (for runtime efficiency)
-	) {
-		super(scope, 0);
-	}
-
-	getType(): ScalarType {
-		return this.columnType;
-	}
-
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	getRelations(): readonly [] {
-		return [];
-	}
-
-	withChildren(newChildren: readonly PlanNode[]): PlanNode {
-		if (newChildren.length !== 0) {
-			quereusError(`ColumnReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
-		}
-		return this; // No children, so no change
-	}
-
-	override toString(): string {
-		const columnName = this.expression.alias ??
-			(this.expression.schema ? this.expression.schema + '.' : '') + this.expression.name;
-		return columnName;
-	}
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		return {
-			column: this.expression.alias ?? this.expression.name,
-			schema: this.expression.schema,
-			attributeId: this.attributeId,
-			resultType: formatScalarType(this.columnType)
-		};
-	}
-}
-
-/**
- * Represents a reference to a parameter (placeholder in a prepared statement).
- * The actual value will be provided at execution time.
- */
-export class ParameterReferenceNode extends PlanNode implements ZeroAryScalarNode {
-	override readonly nodeType = PlanNodeType.ParameterReference;
-
-	constructor(
-		scope: Scope,
-		public readonly expression: AST.ParameterExpr, // Original AST expression for this parameter
-		public readonly nameOrIndex: string | number, // Parameter name (e.g., ':foo') or 1-based index
-		public readonly targetType: ScalarType,
-	) {
-		super(scope, 0.01);
-	}
-
-	getType(): ScalarType {
-		return this.targetType;
-	}
-
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	getRelations(): readonly [] {
-		return [];
-	}
-
-	withChildren(newChildren: readonly PlanNode[]): PlanNode {
-		if (newChildren.length !== 0) {
-			quereusError(`ParameterReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
-		}
-		return this; // No children, so no change
-	}
-
-	override toString(): string {
-		return `:${this.nameOrIndex}`;
-	}
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		return {
-			parameter: this.nameOrIndex,
-			resultType: formatScalarType(this.targetType)
-		};
-	}
-}
-
-export class FunctionReferenceNode extends PlanNode {
-	override readonly nodeType = PlanNodeType.TableFunctionReference;
-
-	constructor(
-		scope: Scope,
-		public readonly functionSchema: FunctionSchema,
-		public readonly targetType: BaseType,
-	) {
-		super(scope);
-	}
-
-	// Type has to be determined by scalar or relation call node
-	getType(): BaseType {
-		return this.targetType;
-	}
-
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	getRelations(): readonly [] {
-		return [];
-	}
-
-	withChildren(newChildren: readonly PlanNode[]): PlanNode {
-		if (newChildren.length !== 0) {
-			quereusError(`FunctionReferenceNode expects 0 children, got ${newChildren.length}`, StatusCode.INTERNAL);
-		}
-		return this; // No children, so no change
-	}
-
-	override toString(): string {
-		return `${this.functionSchema.name}`;
-	}
-
-	override getLogicalAttributes(): Record<string, unknown> {
-		return {
-			function: this.functionSchema.name,
-			numArgs: this.functionSchema.numArgs,
-			targetType: this.targetType.typeClass
-		};
-	}
-}

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

@@ -1,73 +0,0 @@
-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

@@ -1,86 +0,0 @@
-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,
-		};
-	}
-}