Skip to main content

Module query

sqry_core

Module query 

Source
Expand description

Query language for AST-aware code search Query language for AST-aware code search

This module provides a powerful query language for searching code based on semantic properties like symbol type, name patterns, language, and more.

§Query Parsing

All queries are parsed through the boolean AST parser:

§Recommended Entry Points

Use CaseFunctionNotes
Query executionQueryExecutor::execute_on_graphMost common - handles everything
AST accessQueryParser::parse_queryBoolean queries only

§Query Language

The boolean query language supports:

  • Boolean operators: AND, OR, NOT
  • Comparison operators: : (equal), ~= (regex), >, <, >=, <=
  • Field types: kind, name, path, lang, text, and plugin-specific fields
  • Values: strings, regex patterns, numbers, booleans
  • Grouping: parentheses for precedence

§Core Types

  • Query - Complete query with root expression
  • Expr - Expression nodes (Or, And, Not, Condition)
  • Condition - Field-operator-value conditions
  • Operator - Comparison operators
  • Value - Values in conditions

§Error Handling

All errors use QueryError which wraps:

§Performance

The query lexer uses a thread-local buffer pool to reduce allocations:

  • Allocation efficiency: 80% fewer heap allocations vs creating fresh lexers
  • Memory efficiency: Reuses token buffers across multiple tokenize calls
  • Thread-safe: Each thread has its own isolated pool
  • Configurable: Can be tuned or disabled via environment variables

§Lexer Pool Configuration

The lexer pool can be configured via environment variables:

# Pool size (default: 4 lexers per thread)
export SQRY_LEXER_POOL_MAX=8

# Buffer capacity limit (default: 256 tokens)
export SQRY_LEXER_POOL_MAX_CAP=512

# Shrink ratio (default: 8x)
export SQRY_LEXER_POOL_SHRINK_RATIO=4

# Disable pooling (for latency-critical workloads)
export SQRY_LEXER_POOL_MAX=0

Performance characteristics:

  • Simple queries (<10 tokens): ~380ns (pooled) vs ~223ns (fresh) – pooling adds overhead
  • Long queries (>100 tokens): ~18.2µs (pooled) vs ~19.1µs (fresh) – pooling saves ~4%
  • High-throughput workloads: Pool reduces GC pressure and memory fragmentation

Recommendation: Keep pooling enabled (default) for most workloads. The overhead (~150ns per query) is negligible compared to typical query execution time (>10ms). Disable only for latency-critical single-query scenarios.

§Examples

ⓘ
use sqry_core::query::QueryParser;

// Find all async functions
let query = QueryParser::parse_query("kind:function AND async:true").unwrap();

// Find test functions (using regex)
let query = QueryParser::parse_query("kind:function AND name~=/^test_/").unwrap();

// Find functions OR methods in Rust files
let query = QueryParser::parse_query("(kind:function OR kind:method) AND lang:rust").unwrap();

// Find non-test functions
let query = QueryParser::parse_query("kind:function AND NOT name~=/test/").unwrap();

Re-exports§

pub use error::ExecutionError;
pub use error::LexError;
pub use error::ParseError;
pub use error::QueryError;
pub use error::RichQueryError;
pub use error::ValidationError;
pub use lexer::Lexer;
pub use lexer::Token;
pub use lexer::TokenType;
pub use optimizer::Optimizer;
pub use parsed_query::ParsedQuery;
pub use parser_new::Parser as QueryParser;
pub use plan::CacheStatus;
pub use plan::ExecutionStep;
pub use plan::QueryPlan;
pub use registry::FieldRegistry;
pub use registry::core_fields;
pub use types::Condition;
pub use types::Expr;
pub use types::Field;
pub use types::FieldDescriptor;
pub use types::FieldType;
pub use types::JoinEdgeKind;
pub use types::JoinExpr;
pub use types::Operator;
pub use types::PipelineQuery;
pub use types::PipelineStage;
pub use types::Query as QueryAST;
pub use types::RegexFlags;
pub use types::RegexValue;
pub use types::Span;
pub use types::Value;
pub use validator::ContradictionWarning;
pub use validator::Validator;
pub use pipeline::AggregationResult;
pub use pipeline::CountResult;
pub use pipeline::GroupByResult;
pub use pipeline::StatsResult;
pub use pipeline::TopResult;
pub use builder::BuildError;
pub use builder::ConditionBuilder;
pub use builder::QueryBuilder;
pub use builder::RegexBuilder;
pub use results::JoinMatch;
pub use results::JoinResults;
pub use results::QueryMatch;
pub use results::QueryOutput;
pub use results::QueryResults;

Modules§

builder
Query Builder API for type-safe programmatic query construction
cache
Query caching module
error
Error types for the query language
lexer
Lexer for the query language
optimizer
Query optimizer for efficient execution
parsed_query
ParsedQuery - canonical AST representation for indexed and non-indexed flows
parser_new
Parser for the query language
pipeline
Pipeline/aggregation result types for post-query analysis.
plan
Query execution plan types for –explain output
regex_cache
Regex compilation caching for query performance
registry
Field registry for query validation and optimization
results
Query results with Arc-based ownership for zero-copy access.
security
Security controls for query execution
types
Core types for the query language
validator
Semantic validation for query ASTs

Structs§

CircularConfig
Configuration for circular dependency detection
DuplicateConfig
Configuration for duplicate detection
DuplicateGroup
A group of duplicate symbols
QueryExecutor
Executes queries against code using CodeGraph.
RepoFilter
Filter helper for repository scoping predicates (repo:).

Enums§

CircularType
Type of circular dependency to detect
DuplicateType
Type of duplicate detection
UnusedScope
Scope for unused analysis

Functions§

build_duplicate_groups_graph
Find all duplicate groups in the graph.
compute_reachable_set_graph
Compute the set of reachable nodes from entry points via BFS traversal.
execute_pipeline_stage
Execute a single pipeline stage on query results.
find_all_cycles_graph
Find all cycles in the graph using call or import edges.
find_unused_nodes
Find all unused nodes in the graph that match the given scope.
is_node_in_cycle
Check if a specific node is part of a cycle.
is_node_unused
Check if a specific node is unused based on the scope filter.