Struct QueryExecutor 

pub struct QueryExecutor { /* private fields */ }

Executes queries against code using CodeGraph.

The executor loads a CodeGraph from disk and evaluates queries directly against graph nodes using execute_on_graph().

Implementations

impl QueryExecutor

pub fn new() -> Self

Create a new query executor

pub fn with_plugin_manager(plugin_manager: PluginManager) -> Self

Create a query executor with a custom plugin manager

pub fn plugin_manager(&self) -> &PluginManager

Return the plugin manager used by this executor.

pub fn with_validation_options(self, options: ValidationOptions) -> Self

Configure validation options (e.g., fuzzy field tolerance)

pub fn without_parallel(self) -> Self

Disable parallel query execution (for A/B performance testing)

pub fn cache_stats(&self) -> (CacheStats, CacheStats)

Get cache statistics (for monitoring/debugging)

pub fn get_query_plan(&self, query_str: &str) -> Result<QueryPlan>

Get query execution plan for –explain

Parses the query and returns detailed execution plan with timing, cache status, and optimization information.

Errors

Returns anyhow::Error when query parsing, validation, or optimization fails.

pub fn parse_query_ast(&self, query_str: &str) -> Result<Arc<ParsedQuery>>

Parse query string using boolean AST parser with caching

This method:

1. Checks AST parse cache for existing ParsedQuery
2. On cache miss: parses query, validates, extracts repo filter, normalizes
3. Caches the ParsedQuery for future reuse

Arguments

• query_str - Query string to parse (boolean syntax)

Returns

• Ok(Arc<ParsedQuery>) - Cached or freshly parsed query
• Err(...) - Parse error, validation error, or repo filter error

Performance

• Cache hit: ~15-20ns (Arc clone + hash lookup)
• Cache miss: ~1.6µs (lex + parse + validate + normalize)

Example

let executor = QueryExecutor::new();
let parsed = executor.parse_query_ast("kind:function AND name:test")?;
// parsed.ast contains the boolean expression
// parsed.repo_filter contains any repo: predicates
// parsed.normalized is the cache key (repo predicates stripped)

Errors

Returns anyhow::Error when parsing, validation, or normalization fails.

impl QueryExecutor

pub fn execute_on_graph(&self, query: &str, path: &Path) -> Result<QueryResults>

Execute query using CodeGraph.

Loads the CodeGraph from disk (or cache) and evaluates the query directly against graph nodes.

Arguments

• query - The query string to parse and execute
• path - Directory path containing the .sqry/graph/snapshot.sqry file

Returns

QueryResults containing matched NodeIds with Arc-based accessors.

Errors

Returns an error if:

• No graph exists at the path (run sqry index first)
• Query parsing fails
• Predicate evaluation fails

Example

let executor = QueryExecutor::new();
let results = executor.execute_on_graph("kind:function", Path::new("/my/project"))?;
for m in results.iter() {
    println!("{}: {}", m.kind().as_str(), m.name().unwrap_or_default());
}

pub fn execute_on_graph_with_variables( &self, query: &str, path: &Path, variables: Option<&HashMap<String, String>>, ) -> Result<QueryResults>

Execute query with variable substitution.

Variables in the query (e.g., $type) are replaced with values from the provided map before evaluation.

Errors

Returns an error if graph loading, query parsing, variable resolution, or predicate evaluation fails.

pub fn execute_join( &self, query: &str, path: &Path, variables: Option<&HashMap<String, String>>, ) -> Result<JoinResults>

Execute a join query, returning matched node pairs.

The query must have a Join expression at its root level.

Errors

Returns an error if graph loading, query parsing, or join evaluation fails.

pub fn execute_pipeline( &self, query: &str, stages: &[PipelineStage], path: &Path, variables: Option<&HashMap<String, String>>, ) -> Result<Vec<AggregationResult>>

Execute a pipeline query (base query + aggregation stages).

Errors

Returns an error if graph loading, query parsing, or pipeline execution fails.

pub fn execute_full( &self, query: &str, path: &Path, variables: Option<&HashMap<String, String>>, ) -> Result<QueryOutput>

Execute a full query that may be a regular query, join, or pipeline.

Detects the query type and dispatches to the appropriate executor.

Errors

Returns an error if graph loading, query parsing, or execution fails.

Trait Implementations

impl Default for QueryExecutor

fn default() -> Self

Returns the “default value” for a type.