Struct QueryPlanner 

pub struct QueryPlanner { /* private fields */ }

Query planner for hybrid MATCH + NEAR queries.

Implementations

impl QueryPlanner

pub fn new() -> Self

Creates a new query planner with default thresholds.

pub fn with_thresholds(graph_first: f64, vector_first: f64) -> Self

Creates a planner with custom selectivity thresholds.

pub fn choose_strategy( &self, estimated_selectivity: Option<f64>, ) -> ExecutionStrategy

Chooses the optimal execution strategy based on estimated selectivity.

pub fn choose_strategy_with_cbo( &self, stats: &CollectionStats, filter: Option<&Condition>, k: usize, ) -> ExecutionStrategy

Chooses strategy using CBO with collection statistics and optional filter.

Uses calibrated OperationCostFactors from stats.calibrated_cost_factors (when available) to derive I/O and CPU weights for the candidate filter cost. Falls back to OperationCostFactors::default() when no calibrated factors exist, reproducing the historical 0.2 / 0.8 I/O/CPU split.

pub fn choose_strategy_with_cbo_and_overfetch( &self, stats: &CollectionStats, filter: Option<&Condition>, k: usize, ) -> (ExecutionStrategy, usize)

Like choose_strategy_with_cbo but also returns the CBO-computed over-fetch factor.

Returns (strategy, over_fetch) where over_fetch is a multiplier for k when doing vector-first search with a selective metadata filter:

• VectorFirst with filter: (1 / selectivity).clamp(1, 64)
• VectorFirst without filter: 1
• GraphFirst: 1 (graph pre-filters, no over-fetch needed)
• Parallel: 2 (merge overhead)

pub fn stats(&self) -> &QueryStats

Returns a reference to the query statistics.

pub fn record_cbo_feedback( &self, dataset_size: usize, ef_search: usize, actual_ms: f64, )

Records a CBO feedback observation (issue #469).

Called after each vector query with the dataset size, ef_search used, and the actual wall-clock duration. The feedback loop adjusts ms_per_cost_unit via EMA with α=0.05 after MIN_SAMPLES observations.

pub fn adjusted_ms_per_cost_unit(&self) -> Option<f64>

Returns the feedback-adjusted ms_per_cost_unit, if available.

Returns None until the feedback loop has seen enough observations. The planner falls back to the static calibration default in that case.

pub fn cbo_sample_count(&self) -> u64

Returns the total number of CBO feedback samples recorded.

Used by EXPLAIN ANALYZE to surface confidence of the calibration.

pub fn estimate_selectivity( &self, label_count: u64, total_nodes: u64, rel_type_count: u64, total_edges: u64, ) -> f64

Estimates selectivity based on label and relationship type counts.

This is a heuristic based on the principle that:

• Rare labels/types → low selectivity → GraphFirst
• Common labels/types → high selectivity → VectorFirst

pub fn choose_hybrid_strategy( &self, has_order_by_similarity: bool, has_filter: bool, limit: Option<u64>, estimated_selectivity: Option<f64>, ) -> HybridExecutionPlan

Choose optimal strategy for hybrid queries with ORDER BY similarity().

When ORDER BY similarity() is present, we optimize for:

1. Always execute vector search first (it naturally orders by similarity)
2. Apply filters as post-processing to preserve ordering
3. Use early termination when LIMIT is specified

Arguments

• has_order_by_similarity - True if ORDER BY similarity() is in query
• has_filter - True if WHERE clause with non-vector conditions
• limit - Optional LIMIT value for early termination optimization
• estimated_selectivity - Optional estimated filter selectivity

pub fn estimate_cost( &self, plan: &HybridExecutionPlan, candidate_count: u64, ) -> u64

Estimate cost in microseconds for a given execution plan.

Uses runtime statistics to estimate total query cost.

Trait Implementations

impl Debug for QueryPlanner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for QueryPlanner

fn default() -> QueryPlanner

Returns the “default value” for a type.