@quereus/quereus 0.7.3 → 0.7.5

package/src/planner/rules/aggregate/rule-aggregate-streaming.ts

@@ -1,162 +0,0 @@
-/**
- * Rule: Aggregate Streaming
- *
- * Required Characteristics:
- * - Node must support aggregation operations (AggregationCapable interface)
- * - Node must be relational (produces rows)
- * - Node must be read-only (no side effects for streaming)
- *
- * Applied When:
- * - Logical aggregate node needs physical streaming implementation
- * - Source data can be processed incrementally
- *
- * Benefits: Enables streaming aggregation with proper grouping order, memory efficient processing
- */
-
-import { createLogger } from '../../../common/logger.js';
-import type { PlanNode, ScalarPlanNode, Attribute } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { StreamAggregateNode } from '../../nodes/stream-aggregate.js';
-import { SortNode } from '../../nodes/sort.js';
-import {
-	PlanNodeCharacteristics,
-	CapabilityDetectors,
-	type AggregationCapable
-} from '../../framework/characteristics.js';
-
-const log = createLogger('optimizer:rule:aggregate-streaming');
-
-export function ruleAggregateStreaming(node: PlanNode, _context: OptContext): PlanNode | null {
-	// Guard: node must support aggregation operations
-	if (!CapabilityDetectors.isAggregating(node)) {
-		return null;
-	}
-
-	log('Applying aggregate streaming rule to node %s', node.id);
-
-	// Get aggregation characteristics
-	const aggregateNode = node as AggregationCapable;
-	const groupingKeys = aggregateNode.getGroupingKeys();
-	const aggregateExpressions = aggregateNode.getAggregateExpressions();
-
-	// Check if we can stream the aggregation over the source
-	const source = aggregateNode.getSource();
-
-	// Check if streaming aggregation is beneficial
-	if (!aggregateNode.canStreamAggregate()) {
-		log('Node cannot use streaming aggregation, skipping');
-		return null;
-	}
-
-	if (groupingKeys.length > 0) {
-		// Need to ensure ordering for streaming aggregate
-		// Check if source already provides the required ordering
-		const sourceOrdering = PlanNodeCharacteristics.getOrdering(source);
-		const needsSort = !isOrderedForGrouping(sourceOrdering, groupingKeys);
-
-		let sortedSource = source;
-		if (needsSort) {
-			// Insert sort to ensure proper grouping order
-			const sortKeys = groupingKeys.map(expr => ({
-				expression: expr,
-				direction: 'asc' as const,
-				nulls: undefined
-			}));
-
-			sortedSource = new SortNode(node.scope, source, sortKeys);
-			log('Inserted sort for grouping keys');
-		} else {
-			log('Source already provides required ordering for streaming');
-		}
-
-		// Create combined attributes preserving attribute IDs
-		const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
-
-		// Convert aggregate expressions to match StreamAggregateNode interface
-		const streamAggregates = aggregateExpressions.map(agg => ({
-			expression: agg.expr,
-			alias: agg.alias
-		}));
-
-		const result = new StreamAggregateNode(
-			node.scope,
-			sortedSource,
-			groupingKeys,
-			streamAggregates,
-			undefined, // estimatedCostOverride
-			finalAttrs
-		);
-
-		log('Transformed aggregation to StreamAggregateNode with %s', needsSort ? 'sort' : 'existing order');
-		return result;
-	} else {
-		// No GROUP BY - can stream aggregate without sorting
-		const finalAttrs = combineAttributes(node.getAttributes(), source.getAttributes());
-
-		// Convert aggregate expressions to match StreamAggregateNode interface
-		const streamAggregates = aggregateExpressions.map(agg => ({
-			expression: agg.expr,
-			alias: agg.alias
-		}));
-
-		const result = new StreamAggregateNode(
-			node.scope,
-			source,
-			groupingKeys,
-			streamAggregates,
-			undefined, // estimatedCostOverride
-			finalAttrs
-		);
-
-		log('Transformed aggregation to StreamAggregateNode without sort');
-		return result;
-	}
-}
-
-/**
- * Check if source ordering matches grouping requirements for streaming
- */
-function isOrderedForGrouping(
-	_ordering: { column: number; desc: boolean }[] | undefined,
-	_groupingKeys: readonly ScalarPlanNode[]
-): boolean {
-	// TODO: Implement proper ordering analysis
-	// For now, conservatively return false to always sort
-	// This should check if the ordering covers all grouping keys in order
-	return false;
-}
-
-/**
- * Combine attributes from aggregate and source, avoiding duplicates by name
- * This preserves attribute IDs while ensuring unique column names
- */
-function combineAttributes(aggregateAttrs: readonly Attribute[], sourceAttrs: readonly Attribute[]): Attribute[] {
-	const seenNames = new Set<string>();
-	const combinedAttrs: Attribute[] = [];
-
-	// Add aggregate attributes first (GROUP BY + aggregates)
-	for (const attr of aggregateAttrs) {
-		combinedAttrs.push(attr);
-		seenNames.add(attr.name);
-	}
-
-	// Add source attributes that aren't already present by name
-	for (const attr of sourceAttrs) {
-		if (!seenNames.has(attr.name)) {
-			combinedAttrs.push(attr);
-			seenNames.add(attr.name);
-		}
-	}
-
-	// Final deduplication pass
-	const uniqueByName = new Set<string>();
-	const deduped: any[] = [];
-	for (const attr of combinedAttrs) {
-		if (!uniqueByName.has(attr.name)) {
-			deduped.push(attr);
-			uniqueByName.add(attr.name);
-		}
-	}
-
-	return deduped;
-}

package/src/planner/rules/cache/rule-cte-optimization.ts

@@ -1,79 +0,0 @@
-/**
- * Rule: CTE Optimization
- *
- * Required Characteristics:
- * - Node must support CTE operations (CTECapable interface)
- * - Node must be relational (produces rows)
- * - Source must be cacheable for materialization
- *
- * Applied When:
- * - CTE would benefit from materialization/caching based on cost analysis
- *
- * Benefits: Reduces redundant computation for repeated CTE access
- */
-
-import { createLogger } from '../../../common/logger.js';
-import type { PlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { CTENode } from '../../nodes/cte-node.js';
-import { CacheNode } from '../../nodes/cache-node.js';
-import { CapabilityDetectors, CachingAnalysis, PlanNodeCharacteristics, type CTECapable } from '../../framework/characteristics.js';
-
-const log = createLogger('optimizer:rule:cte-optimization');
-
-export function ruleCteOptimization(node: PlanNode, context: OptContext): PlanNode | null {
-	// Guard: node must support CTE operations
-	if (!CapabilityDetectors.isCTE(node)) {
-		return null;
-	}
-
-	// Get CTE characteristics
-	const cteNode = node as CTECapable;
-	log('Optimizing CTE %s', cteNode.cteName);
-
-	// Source is already optimized by framework
-	const source = cteNode.getCTESource();
-
-	// Heuristics for when to cache CTEs:
-	// 1. CTE has materialization hint
-	// 2. CTE is estimated to be reasonably sized
-	// 3. CTE is not already cached
-	const sourceSize = PlanNodeCharacteristics.estimatesRows(source);
-	const isAlreadyCached = CapabilityDetectors.isCached(source) && source.isCached();
-	const shouldCache = (
-		cteNode.materializationHint === 'materialized' ||
-		(sourceSize > 0 && sourceSize < context.tuning.cte.maxSizeForCaching)
-	) && !isAlreadyCached;
-
-	if (shouldCache) {
-		log('Adding cache to CTE %s (estimated rows: %d)', cteNode.cteName, sourceSize);
-
-		// Use characteristics-based cache threshold calculation
-		const cacheThreshold = Math.min(
-			CachingAnalysis.getCacheThreshold(source),
-			context.tuning.cte.maxCacheThreshold
-		);
-
-		const cachedSource = new CacheNode(
-			source.scope,
-			source,
-			'memory',
-			cacheThreshold
-		);
-
-		// Create new CTE with cached source (specific to CTENode implementation)
-		const result = new CTENode(
-			node.scope,
-			cteNode.cteName,
-			cteNode.columns,
-			cachedSource,
-			cteNode.materializationHint,
-			cteNode.isRecursive
-		);
-
-		log('Created CTE with caching');
-		return result;
-	}
-
-	return null; // No transformation needed
-}

package/src/planner/rules/cache/rule-materialization-advisory.ts

@@ -1,77 +0,0 @@
-/**
- * Rule: Materialization Advisory
- *
- * Required Characteristics:
- * - Node must be non-relational with relational children
- * - Children must be cacheable based on reference analysis
- * - Children must benefit from materialization
- *
- * Applied When:
- * - Transition from non-relational to relational subtrees
- * - Relational subtrees would benefit from caching
- *
- * Benefits: Reduces redundant computation for repeated scans and loop contexts
- */
-
-import { createLogger } from '../../../common/logger.js';
-import type { PlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { MaterializationAdvisory } from '../../cache/materialization-advisory.js';
-import { PlanNodeCharacteristics } from '../../framework/characteristics.js';
-
-const log = createLogger('optimizer:rule:materialization-advisory');
-
-export function ruleMaterializationAdvisory(node: PlanNode, context: OptContext): PlanNode | null {
-	// Apply this rule when we're at a non-relational node that has relational children
-	// This captures transitions into relational subtrees (queries, subqueries, CTEs, etc.)
-
-	// Check if this is a non-relational node using characteristics
-	if (PlanNodeCharacteristics.isRelational(node)) {
-		// This is already a relational node, don't apply here
-		return null;
-	}
-
-	// Check if this node has any relational children
-	const relations = node.getRelations();
-	if (relations.length === 0) {
-		// No relational children, nothing to analyze
-		return null;
-	}
-
-	log('Applying materialization advisory at transition from %s to relational children', node.getType().typeClass);
-
-	try {
-		// Create advisory with current tuning parameters
-		const advisory = new MaterializationAdvisory(context.tuning);
-
-		// We need to analyze and potentially transform each relational subtree
-		let anyTransformed = false;
-
-		// For each relational child, analyze and transform its entire subtree
-		for (const relation of relations) {
-			const transformedRelation = advisory.analyzeAndTransform(relation);
-			if (transformedRelation !== relation) {
-				anyTransformed = true;
-				log('Transformed relational subtree under %s node', node.getType().typeClass);
-			}
-		}
-
-		// If any relational children were transformed, we need to return a transformed node
-		// However, since we can't easily reconstruct the parent node with new relational children
-		// (as discussed in the earlier implementation), we'll analyze the entire node
-		if (anyTransformed) {
-			// Re-analyze the entire tree rooted at this node
-			const fullTransform = advisory.analyzeAndTransform(node);
-			if (fullTransform !== node) {
-				return fullTransform;
-			}
-		}
-
-		return null;
-
-	} catch (error) {
-		log('Error in materialization advisory: %s', error);
-		// Don't fail optimization - just skip caching
-		return null;
-	}
-}

package/src/planner/rules/cache/rule-mutating-subquery-cache.ts

@@ -1,104 +0,0 @@
-/**
- * Rule: Mutating Subquery Cache Injection
- *
- * Required Characteristics:
- * - Node must be a join operation (JoinCapable interface)
- * - Right side must contain operations with side effects (readonly=false)
- * - Right side must not already be cached
- *
- * Applied When:
- * - Join has mutating operations on right side that could be executed multiple times
- *
- * Benefits: Prevents mutating subqueries from being executed multiple times in nested loop joins
- */
-
-import { createLogger } from '../../../common/logger.js';
-import { PlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { CacheNode } from '../../nodes/cache-node.js';
-import { JoinNode } from '../../nodes/join-node.js';
-import { PlanNodeCharacteristics, CapabilityDetectors, CachingAnalysis, type JoinCapable } from '../../framework/characteristics.js';
-
-const log = createLogger('optimizer:rule:mutating-subquery-cache');
-
-export function ruleMutatingSubqueryCache(node: PlanNode, _context: OptContext): PlanNode | null {
-	// Guard: node must support join operations
-	if (!CapabilityDetectors.isJoin(node)) {
-		return null;
-	}
-
-	log('Checking join operation for side effects on right side');
-
-	// Get join-specific characteristics
-	const joinNode = node as JoinCapable;
-	const rightSide = joinNode.getRightSource();
-
-	// Check if right side contains operations with side effects
-	const hasSideEffects = containsOperationsWithSideEffects(rightSide);
-	if (!hasSideEffects) {
-		log('Right side does not contain operations with side effects, skipping');
-		return null;
-	}
-
-	// Check if right side is already cached
-	if (CapabilityDetectors.isCached(rightSide) && rightSide.isCached()) {
-		log('Right side is already cached, skipping');
-		return null;
-	}
-
-	log('Detected operations with side effects on right side of join, injecting cache');
-
-	// Calculate appropriate cache threshold using characteristics
-	const threshold = CachingAnalysis.getCacheThreshold(rightSide);
-
-	// Wrap the right side with a cache node
-	const cachedRightSide = new CacheNode(
-		rightSide.scope,
-		rightSide,
-		'memory',
-		threshold
-	);
-
-	// Create new join node with cached right side
-	// Note: We still need to use specific constructor since we don't have a generic join builder yet
-	const result = new JoinNode(
-		node.scope,
-		joinNode.getLeftSource(),
-		cachedRightSide,
-		joinNode.getJoinType(),
-		joinNode.getJoinCondition(),
-		// Special case: for JOINs, we also need to check if any of the join conditions
-		// reference columns from the mutating subquery (via USING clause)
-		joinNode.getUsingColumns()
-	);
-
-	log('Successfully injected cache for operations with side effects (threshold: %d)', threshold);
-	return result;
-}
-
-/**
- * Recursively check if a plan tree contains operations with side effects
- * Uses characteristics-based analysis instead of hard-coded node type checks
- */
-function containsOperationsWithSideEffects(node: PlanNode): boolean {
-	// Check this node's characteristics
-	if (PlanNodeCharacteristics.hasSideEffects(node)) {
-		return true;
-	}
-
-	// Recursively check all children
-	for (const child of node.getChildren()) {
-		if (containsOperationsWithSideEffects(child)) {
-			return true;
-		}
-	}
-
-	// Check relational children if available (preserved for compatibility)
-	for (const relation of node.getRelations()) {
-		if (containsOperationsWithSideEffects(relation)) {
-			return true;
-		}
-	}
-
-	return false;
-}

package/src/planner/rules/join/rule-join-greedy-commute.ts

@@ -1,48 +0,0 @@
-import { createLogger } from '../../../common/logger.js';
-import type { PlanNode, RelationalPlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { JoinNode } from '../../nodes/join-node.js';
-
-const log = createLogger('optimizer:rule:join-greedy-commute');
-
-/**
- * Rule: Join Greedy Commute
- *
- * Simple heuristic: for INNER joins, prefer the smaller input on the left to drive nested-loop-like cost.
- * This uses children estimatedRows (influenced by pushdown/growth) and swaps left/right when beneficial.
- *
- * Safety:
- * - INNER joins are commutative; ColumnReferenceNode uses attribute IDs, so swapping sides preserves semantics.
- * - We do NOT change associativity; we only commute immediate children of a JoinNode.
- */
-export function ruleJoinGreedyCommute(node: PlanNode, _context: OptContext): PlanNode | null {
-  if (!(node instanceof JoinNode)) return null;
-  if (node.joinType !== 'inner' && node.joinType !== 'cross') return null;
-
-  const leftRows = node.getLeftSource().estimatedRows ?? Number.POSITIVE_INFINITY;
-  const rightRows = node.getRightSource().estimatedRows ?? Number.POSITIVE_INFINITY;
-
-  // Prefer known finite estimatedRows; also detect <=1 row driver on either side
-  const leftIsSingleton = node.getLeftSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
-  const rightIsSingleton = node.getRightSource().physical.uniqueKeys?.some(k => k.length === 0) === true;
-
-  // If right is strictly better driver (smaller or singleton), swap
-  const shouldSwap = (rightIsSingleton && !leftIsSingleton) || (!rightIsSingleton && !leftIsSingleton && rightRows < leftRows);
-  if (!shouldSwap) return null;
-
-  log('Commuting join children to place smaller input on the left (leftRows=%s, rightRows=%s)', String(leftRows), String(rightRows));
-
-  // Swap children; condition stays the same (attribute IDs are stable)
-  const swapped = new JoinNode(
-    node.scope,
-    node.getRightSource() as RelationalPlanNode,
-    node.getLeftSource() as RelationalPlanNode,
-    node.getJoinType(),
-    node.getJoinCondition(),
-    node.getUsingColumns()
-  );
-
-  return swapped;
-}
-
-

package/src/planner/rules/join/rule-join-key-inference.ts

@@ -1,35 +0,0 @@
-import { createLogger } from '../../../common/logger.js';
-import type { PlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-import { JoinNode } from '../../nodes/join-node.js';
-import { BinaryOpNode } from '../../nodes/scalar.js';
-import { ColumnReferenceNode } from '../../nodes/reference.js';
-
-const log = createLogger('optimizer:rule:join-key-inference');
-
-/**
- * Rule: Join Key Inference
- *
- * Detect simple equi-join predicates (left.col = right.pk) and propagate
- * inner/cross join unique keys (already handled by JoinNode.computePhysical),
- * with a hook for future FK->PK inference (not implemented here yet).
- */
-export function ruleJoinKeyInference(node: PlanNode, _context: OptContext): PlanNode | null {
-  if (!(node instanceof JoinNode)) return null;
-  if (node.joinType !== 'inner' && node.joinType !== 'cross') return null;
-
-  const cond = node.getJoinCondition();
-  if (!cond || !(cond instanceof BinaryOpNode)) return null;
-  if (cond.expression.operator !== '=') return null;
-
-  // Simple left.col = right.col pattern check; placeholder for future FK->PK detection
-  const leftIsCol = cond.left instanceof ColumnReferenceNode;
-  const rightIsCol = cond.right instanceof ColumnReferenceNode;
-  if (!leftIsCol || !rightIsCol) return null;
-
-  log('Detected equi-join predicate; JoinNode.computePhysical will preserve side keys');
-  // No structural change needed now; computePhysical on JoinNode already preserves side keys
-  return null;
-}
-
-