Struct QueryEngine 

pub struct QueryEngine { /* private fields */ }

Query engine with caching and statistics

Implementations

impl QueryEngine

pub fn new( storage: Arc<StorageEngine>, schema: Arc<SchemaManager>, _memory: Arc<MemoryManager>, config: &Config, ) -> Result<Self>

Create a new query engine

pub async fn execute(&self, cql: &str) -> Result<QueryResult>

Execute a CQL query

This is the parent of the query span tree (epic #1031, issue #1035): the query.execute span created here is the context every read-path span (issue #1034) and SELECT sub-span nests under. Bounded span attributes (plan type, access path, rows returned) are recorded once the result is known via Self::update_execution_stats; the query text is never attached.

pub async fn execute_streaming( &self, cql: &str, config: StreamingConfig, ) -> Result<QueryResultIterator>

Execute a CQL query with streaming results (Issue #280)

Returns a QueryResultIterator that yields rows incrementally via a bounded channel, enabling memory-efficient processing of large result sets.

Arguments

• cql - The CQL query string to execute (must be a SELECT statement)
• config - Streaming configuration (buffer size, chunk hints)

Errors

Returns an error if:

• Query is not a SELECT statement
• SQL syntax is invalid
• Query execution fails

Memory Budget

The streaming approach stays within the 128MB target by using bounded channels and processing rows incrementally rather than materializing all results.

pub async fn execute_with_params( &self, cql: &str, params: &[Value], ) -> Result<QueryResult>

Execute a query with positional ? parameters (Issue #961).

The supplied params are bound, in source order, into the ? placeholders of the parsed statement before planning and execution, so the bound values participate in partition-key classification, encoding, and typed coercion. A WHERE pk = ? therefore engages the same partition-targeted fast path (#949/#956) as the equivalent literal query.

Binding is currently supported for SELECT statements only. A non-SELECT CQL with parameters, or any use of named (:name) parameters, is rejected with a clear error (named-parameter binding is intentionally out of scope: the SELECT grammar only tokenizes positional ?).

Routing parity with execute (Finding 1)

When the parsed SELECT has zero bind markers and params is empty, this delegates straight back to Self::execute so that a markerless execute_with_params(sql, &[]) is byte-for-byte equivalent to execute(sql) — which since issue #1750 routes every literal SELECT through the modern SELECT optimizer + executor. Only when markers are present (> 0) is the statement bound and driven through that pipeline.

Arity stays strict in both directions: markers > 0 with a wrong params.len() is an error, and markers == 0 with a non-empty params is also an error (a supplied parameter with no placeholder is a caller bug). The latter matches [SelectStatement::bind_parameters]’s contract and the documented strictness of this API.

pub async fn prepare(&self, cql: &str) -> Result<Arc<PreparedQuery>>

Prepare a query for repeated execution

pub async fn execute_prepared( &self, prepared: &PreparedQuery, params: &[Value], ) -> Result<QueryResult>

Execute a prepared query

pub fn stats(&self) -> QueryStats

Get query statistics

pub fn clear_caches(&self)

Clear all caches

pub fn clear_prepared_cache(&self)

Clear prepared statement cache

pub fn clear_plan_cache(&self)

Clear query plan cache

pub fn cache_stats(&self) -> CacheStats

Get cache statistics

pub async fn explain(&self, cql: &str) -> Result<ExplainResult>

Optimize a query (return execution plan without executing)

pub async fn analyze(&self, cql: &str) -> Result<AnalyzeResult>

Analyze query performance

pub async fn has_schema_for_table(&self, table: &str) -> bool

Check if schema is available for a table

pub async fn schema_status(&self, table: &str) -> SchemaStatus

Get detailed schema status for debugging

Trait Implementations

impl Debug for QueryEngine

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

Formats the value using the given formatter.