Struct QueryEngine 

pub struct QueryEngine { /* private fields */ }

Query engine for executing SQL against a projection store.

Holds the schema plus an optional parse cache (AUDIT-2026-04 S3.4). The engine is Clone — the parse cache is shared via Arc so cloned handles hit the same memoised entries.

Implementations

impl QueryEngine

pub fn new(schema: Schema) -> Self

Creates a new query engine with the given schema. No parse cache is attached by default — use Self::with_parse_cache to opt in.

pub fn with_parse_cache(self, max_size: usize) -> Self

Attach an LRU parse cache of the given size. 0 disables caching (every call re-parses).

pub fn with_correlated_cap(self, cap: u64) -> Self

Override the correlated-subquery row-evaluation cap. Defaults to 10,000,000. Queries whose estimated outer_rows × inner_rows_per_iter exceeds this cap fail with QueryError::CorrelatedCardinalityExceeded before the correlated loop runs. Set to u64::MAX to effectively disable.

pub fn parse_cache_stats(&self) -> Option<ParseCacheStats>

Returns a snapshot of parse-cache stats, or None if no cache is attached.

pub fn clear_parse_cache(&self)

Clear the parse cache, if any.

pub fn schema(&self) -> &Schema

Returns a reference to the schema.

pub fn query<S: ProjectionStore>( &self, store: &mut S, sql: &str, params: &[Value], ) -> Result<QueryResult>

Executes a SQL query against the current store state.

Supports SELECT and UNION/UNION ALL queries.

Arguments

• store - The projection store to query
• sql - SQL query string
• params - Query parameters (for $1, $2, etc.)

Example

let result = engine.query(
    &mut store,
    "SELECT name FROM users WHERE id = $1",
    &[Value::BigInt(42)],
)?;

pub fn query_at<S: ProjectionStore>( &self, store: &mut S, sql: &str, params: &[Value], position: Offset, ) -> Result<QueryResult>

Executes a SQL query at a specific log position (point-in-time query).

This enables compliance queries that show the state as it was at a specific point in the log.

Arguments

• store - The projection store to query
• sql - SQL query string
• params - Query parameters
• position - Log position to query at

Example

// Get user state as of log position 1000
let result = engine.query_at(
    &mut store,
    "SELECT * FROM users WHERE id = 1",
    &[],
    Offset::new(1000),
)?;

pub fn query_at_timestamp<S, R>( &self, store: &mut S, sql: &str, params: &[Value], target_ns: i64, resolver: R, ) -> Result<QueryResult>

where S: ProjectionStore, R: FnOnce(i64) -> Option<Offset>,

Executes a query against a historical snapshot selected by wall-clock timestamp (AUDIT-2026-04 L-4).

This is the user-facing ergonomic form of Self::query_at — healthcare auditors ask “what did the chart look like on 2026-01-15?”, not “what was log offset 948,274?”. The caller supplies a resolver callback that translates a Unix-nanosecond timestamp into the log offset whose commit timestamp is the greatest value ≤ the target.

The resolver is a callback rather than a hard dependency so the query crate does not take a direct dep on kimberlite-compliance::audit or the kernel’s audit log. A typical impl performs a binary search on the in-memory audit index.

Errors

• QueryError::UnsupportedFeature if the resolver returns None (no offset exists at or before the target — typically because the log is empty or the timestamp predates genesis).

Example

let resolver = |ts_ns: i64| -> Option<Offset> {
    audit_log.offset_at_or_before(ts_ns)
};
let result = engine.query_at_timestamp(
    &mut store,
    "SELECT * FROM charts WHERE patient_id = $1",
    &[Value::BigInt(42)],
    1_760_000_000_000_000_000, // 2025-10-09T07:06:40Z in ns
    resolver,
)?;

pub fn query_at_timestamp_resolved<S, R>( &self, store: &mut S, sql: &str, params: &[Value], target_ns: i64, resolver: R, ) -> Result<QueryResult>

where S: ProjectionStore, R: FnOnce(i64) -> TimestampResolution,

Executes a query against a historical snapshot selected by wall-clock timestamp, with a resolver that can distinguish the “timestamp predates retention horizon” case from a plain “no offset found”.

v0.6.0 Tier 2 #6: this is the runtime-layer variant of Self::query_at_timestamp used by TenantHandle::query when the resolver has a concrete notion of a retention horizon (e.g. an in-memory timestamp index maintained at append time). The existing query_at_timestamp stays as-is so callers with an Option<Offset> resolver (e.g. ad-hoc binary search over an external index) keep working.

Resolution semantics

• TimestampResolution::Offset(o) → execute at o.
• TimestampResolution::BeforeRetentionHorizon { horizon_ns } → QueryError::AsOfBeforeRetentionHorizon with both the requested and horizon timestamps.
• TimestampResolution::LogEmpty → QueryError::UnsupportedFeature (same message the ergonomic form emits for an empty log).

pub fn explain(&self, sql: &str, params: &[Value]) -> Result<String>

AUDIT-2026-04 S3.3 — render a SQL query’s access plan without executing it.

Returns a deterministic multi-line tree string — same query always produces the same bytes, which lets apps diff plans across schema versions and catch unexpected regressions.

The rendered plan never reveals row data — only table names, column counts, filter presence/absence, and LIMIT bounds. Masked column names render as their source name (masks are applied post-projection and are not a plan concern).

Errors

Any error from parsing or planning (unsupported statement, missing table, etc.) propagates verbatim.

Example

let tree = engine.explain("SELECT * FROM patients WHERE id = $1", &[Value::BigInt(42)])?;
println!("{tree}");
// -> PointLookup [patients, cols=3]

pub fn prepare(&self, sql: &str, params: &[Value]) -> Result<PreparedQuery>

Parses a SQL query without executing it.

Useful for validation or query plan inspection.

Trait Implementations

impl Clone for QueryEngine

fn clone(&self) -> QueryEngine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryEngine

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

Formats the value using the given formatter.