Struct QueryEngine 

pub struct QueryEngine { /* private fields */ }

Manages query execution against the index

Implementations

impl QueryEngine

pub fn new(cache: CacheManager) -> Self

Create a new query engine with the given cache manager

pub fn search_with_metadata( &self, pattern: &str, filter: QueryFilter, ) -> Result<QueryResponse>

Execute a query and return matching results with index metadata

This is the preferred method for programmatic/JSON output as it includes index freshness information that AI agents can use to decide whether to re-index.

pub fn search( &self, pattern: &str, filter: QueryFilter, ) -> Result<Vec<SearchResult>>

Execute a query and return matching results (legacy method)

This method prints warnings to stderr and returns just the results. For programmatic use, prefer search_with_metadata().

pub fn find_symbol(&self, name: &str) -> Result<Vec<SearchResult>>

Search for symbols by exact name match

pub fn search_ast( &self, pattern: &str, lang: Option<Language>, ) -> Result<Vec<SearchResult>>

Search using a Tree-sitter AST pattern

pub fn search_ast_all_files( &self, ast_pattern: &str, filter: QueryFilter, ) -> Result<Vec<SearchResult>>

Execute AST query on all indexed files (no trigram filtering)

WARNING: This method scans the entire codebase (500ms-2s+). In 95% of cases, use –symbols instead which is 10-100x faster.

Algorithm

1. Get all indexed files for the specified language
2. Apply glob/exclude filters to reduce file set
3. Load file contents for all matching files
4. Execute AST query pattern using Tree-sitter
5. Apply remaining filters and return results

Performance

• Parses entire codebase (not just trigram candidates)
• Expected: 500ms-2s for medium codebases, 2-10s for large codebases
• Use –glob to limit scope for better performance

Requirements

• Language must be specified (AST queries are language-specific)
• AST pattern must be valid S-expression syntax

pub fn search_ast_with_text_filter( &self, text_pattern: &str, ast_pattern: &str, filter: QueryFilter, ) -> Result<Vec<SearchResult>>

Search using AST pattern with separate text pattern for trigram filtering

This allows efficient AST queries by:

1. Using text_pattern for Phase 1 trigram filtering (narrows to candidate files)
2. Using ast_pattern for Phase 2 AST matching (structure-aware filtering)

Example

// Find async functions: trigram search for "fn ", AST match for function_item
engine.search_ast_with_text_filter("fn ", "(function_item (async))", filter)?;

pub fn list_by_kind(&self, kind: SymbolKind) -> Result<Vec<SearchResult>>

List all symbols of a specific kind

pub fn get_index_status( &self, ) -> Result<(IndexStatus, bool, Option<IndexWarning>)>

Get index status for programmatic use (doesn’t print warnings)

Returns (status, can_trust_results, warning) tuple for JSON output. This is optimized for AI agents to detect staleness and auto-reindex.

pub fn fresh_index_status( &self, ) -> Result<(IndexStatus, bool, Option<IndexWarning>)>

Index status read from the filesystem, never from the freshness memo.

For check_index_status: an agent asking whether the index is current is exactly the caller that must not be told what was true a second ago.

pub fn index_status_for( &self, scope: Option<&[String]>, ) -> Result<(IndexStatus, bool, Option<IndexWarning>)>

Index status, with scope naming the files a caller’s answer came from.

scope does NOT soften can_trust_results. A stale index always yields can_trust_results: false, because the changes that matter most are the ones scoping cannot see: a newly created file produces no results to intersect with, and an empty result set has no scope at all — which is exactly the case where an agent concludes “no callers” and acts on it.

Scope is used only to describe the impact, via IndexWarning::reason, so a caller can tell “your results may be missing a file you just edited” from “a file in these results has changed”.