Module adaptive 

Adaptive query execution with runtime cardinality feedback.

This module provides adaptive execution capabilities that allow the query engine to adjust its execution strategy based on actual runtime cardinalities.

The key insight is that cardinality estimates can be significantly wrong, especially for complex predicates or skewed data. By tracking actual row counts during execution, we can detect when our estimates are off and potentially re-optimize the remaining query plan.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Optimizer  │────>│ Estimated Cards  │     │ CardinalityFeed │
└─────────────┘     └──────────────────┘     │     back        │
                             │               └────────┬────────┘
                             v                        │
                    ┌──────────────────┐              │
                    │ AdaptiveContext  │<─────────────┘
                    └────────┬─────────┘
                             │
                    ┌────────v─────────┐
                    │ ReoptimizeCheck  │
                    └──────────────────┘

Example

use grafeo_core::execution::adaptive::{AdaptiveContext, CardinalityCheckpoint};

// Set up adaptive context with estimated cardinalities
let mut ctx = AdaptiveContext::new();
ctx.set_estimate("scan_1", 1000.0);
ctx.set_estimate("filter_1", 100.0);  // Expected 10% selectivity

// During execution, record actuals
ctx.record_actual("scan_1", 1000);
ctx.record_actual("filter_1", 500);   // Actual 50% selectivity!

// Check if re-optimization is warranted
if ctx.should_reoptimize() {
    // Re-plan remaining operators with updated statistics
}

Structs

AdaptiveCheckpoint

A checkpoint during adaptive execution where plan switching can occur.

AdaptiveContext

Context for adaptive query execution.

AdaptiveExecutionConfig

Configuration for adaptive execution, built by AdaptivePipelineBuilder.

AdaptiveExecutionResult

Result of executing an adaptive pipeline.

AdaptivePipelineBuilder

Builder for creating adaptive pipelines.

AdaptivePipelineConfig

Configuration for adaptive pipeline execution.

AdaptivePipelineExecutor

High-level adaptive pipeline that executes a pull-based operator with cardinality tracking using push-based infrastructure.

AdaptiveSummary

Summary of adaptive execution statistics.

CardinalityCheckpoint

A checkpoint for tracking cardinality at a specific point in the plan.

CardinalityFeedback

Feedback from runtime execution about actual cardinalities.

CardinalityTrackingOperator

A wrapper operator that tracks cardinality and reports to an adaptive context.

CardinalityTrackingSink

A sink that tracks cardinality of data flowing through it.

CardinalityTrackingWrapper

A wrapper that tracks cardinality for pull-based operators.

SharedAdaptiveContext

Thread-safe wrapper for AdaptiveContext.

Enums

AdaptiveEvent

Event emitted during adaptive execution.

ReoptimizationDecision

Decision about whether to re-optimize a query.

Constants

DEFAULT_REOPTIMIZATION_THRESHOLD

Threshold for deviation that triggers re-optimization consideration. A value of 2.0 means actual cardinality is 2x or 0.5x the estimate.

MIN_ROWS_FOR_REOPTIMIZATION

Minimum number of rows before considering re-optimization. Helps avoid thrashing on small result sets.

Functions

evaluate_reoptimization

Evaluates whether re-optimization should occur based on context.

execute_adaptive

Convenience function to execute a pull-based operator with adaptive tracking.

Type Aliases

AdaptiveEventCallback

Callback for observing adaptive execution events.

PlanFactory

Callback for creating a new plan based on observed cardinalities.