Struct QueryPlanCache 

pub struct QueryPlanCache { /* private fields */ }

Implementations

impl QueryPlanCache

pub fn new(config: PlanCacheConfig) -> Self

Create a new query plan cache.

pub fn with_stats_manager(self, stats_manager: Arc<StatsManager>) -> Self

pub fn set_stats_manager(&self, stats_manager: Arc<StatsManager>)

Set the stats manager after creation

pub fn get(&self, query: &str) -> Option<Arc<CachedPlan>>

Obtaining the cached plan

Parameters

• query: The text of the query

Returns

• Some(Arc<CachedPlan>): Cached plan
• None: No results were found, or there was a hash collision.

pub fn get_with_space( &self, query: &str, space_name: Option<String>, schema_version: Option<u64>, ) -> Option<Arc<CachedPlan>>

Look up a cached plan with space, schema, and parameter type context.

space_name and schema_version are incorporated into the cache key to prevent cross-space plan reuse and stale plans after DDL.

param_type_signature is a hash of parameter types so that the same query with different param types gets a different cache key.

index_version forces replan after index DDL (use the same value that was passed to put_with_context to ensure key matching).

pub fn get_with_full_space( &self, query: &str, space_name: Option<String>, schema_version: Option<u64>, index_version: Option<u64>, ) -> Option<Arc<CachedPlan>>

Look up with space, schema version, AND index version.

the index_version dimension ensures that a plan compiled with a certain index state is not reused after index DDL.

pub fn get_with_full_context( &self, query: &str, space_name: Option<String>, schema_version: Option<u64>, param_type_signature: Option<u64>, index_version: Option<u64>, ) -> Option<Arc<CachedPlan>>

Full-context cache lookup with parameter type signature and index version.

pub fn get_with_context( &self, query: &str, context: PlanCacheContext, ) -> Option<Arc<CachedPlan>>

pub fn put( &self, query: &str, plan: Arc<PhysicalPlan>, param_positions: Vec<ParamPosition>, )

Put the plan in the cache.

stores an Arc<PhysicalPlan> instead of [ExecutionPlan].

Parameters

• query: Query text
• plan: Arena-based physical plan
• param_positions: Information about the positions of the parameters

pub fn put_with_tables( &self, query: &str, plan: Arc<PhysicalPlan>, param_positions: Vec<ParamPosition>, dependent_tables: Vec<String>, )

Put the plan in the cache with dependent tables.

pub fn put_with_context( &self, query: &str, plan: Arc<PhysicalPlan>, param_positions: Vec<ParamPosition>, context: PlanCachePutContext, )

Put the plan with full context (space, schema version, index version, tables).

space_name and schema_version are incorporated into the cache key to prevent cross-space reuse and stale plans after DDL.

param_type_signature is derived from the parameter type declarations (not values) and is included in the cache key.

index_version is incorporated into the cache key to force replan after index DDL (CREATE/DROP index) even when schema_version is unchanged.

stores Arc<PhysicalPlan> — the immutable arena plan.

pub fn get_with_partition( &self, query: &str, spec: &PartitionSpec, ) -> Option<Arc<CachedPlan>>

Look up a cached plan keyed by its physical partition layout.

The key incorporates the layout fingerprint (ranges, source, layout version), so a plan cached under one layout is never reused for a different one. This is the lookup used by callers that already know the current layout (e.g. re-planning against a previous execution’s metadata); plain-text lookups deliberately miss partitioned entries.

pub fn get_with_partition_context( &self, query: &str, spec: &PartitionSpec, context: PlanCacheContext, ) -> Option<Arc<CachedPlan>>

Partition-keyed lookup that additionally scopes by the full compatibility context, matching put_with_partition.

pub fn put_with_partition( &self, query: &str, spec: &PartitionSpec, plan: Arc<PhysicalPlan>, param_positions: Vec<ParamPosition>, context: PlanCachePutContext, )

Store a plan under its physical partition layout key.

Only partitioned plans should use this; the plain-text key is left free so a subsequent lookup that cannot provide the layout does not silently reuse a layout-dependent plan.

pub fn record_execution(&self, query: &str, execution_time_ms: f64)

Record the statistics on the execution of the plan.

Parameter

• query: Query content
• execution_time_ms: Execution time (in milliseconds)

pub fn record_execution_with_space( &self, query: &str, execution_time_ms: f64, space_name: Option<String>, schema_version: Option<u64>, index_version: Option<u64>, param_type_signature: Option<u64>, )

Record execution with space context.

index_version must match the value used during put_with_context to locate the cached plan; otherwise the keys will differ and the record will miss.

param_type_signature must match the signature used during put_with_context (i.e. the hash of the parameter types) or the record will miss for parameterized queries.

pub fn contains(&self, query: &str) -> bool

Check whether the query has been cached.

pub fn invalidate(&self, query: &str) -> bool

Invalidate the cache entry

pub fn invalidate_space(&self, space_name: &str) -> usize

Invalidate all cache entries for a given space.

called after DDL/index/schema changes to force replanning. Iterates all entries and removes those matching the space name.

pub fn get_cache_entries(&self) -> Vec<(Arc<PlanCacheKey>, f64, usize)>

Get cache entries for eviction (internal use)

pub fn increment_eviction_count(&self, count: u64)

Increment eviction count (internal use)

pub fn clear(&self)

Clear all caches.

pub fn stats(&self) -> Arc<PlanCacheStats>

Obtain statistical information

pub fn record_memo_hit(&self)

Record a hit without a cache lookup, for the Level 2 same-shape DML memo that short-circuits before get_with_context. Keeps the hit rate accounting consistent with the regular lookup path.

pub fn stats_snapshot(&self) -> PlanCacheStatsSnapshot

Get statistics snapshot

pub fn cleanup_expired(&self)

Clean up expired entries. Note: moka handles TTL automatically, so this is a no-op

pub fn len(&self) -> usize

Get the number of cached entries

pub fn is_empty(&self) -> bool

Check whether the cache is empty.

pub fn config(&self) -> &PlanCacheConfig

Get the configuration

Trait Implementations

impl Debug for QueryPlanCache

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

Formats the value using the given formatter.

impl Default for QueryPlanCache

fn default() -> Self

Returns the “default value” for a type.