# runtime
`src/features/runtime/api.rs`
The query execution engine. Takes an `ExecuteParams` (scan range, morsel size, parallelism) together with a parsed and planned query, selects a physical execution strategy, and returns a `RowStream`.
---
## Execution
```rust
pub fn execute(handle: &mut StorageHandle, params: ExecuteParams) -> Result<RowStream>
```
Executes a query against a single `StorageHandle`. The planner selects operators based on the current `PlannerStatsSnapshot` and the predicates embedded in `params`.
```rust
pub fn execute_with_request(
handle: &mut StorageHandle,
request: &ThreadCoreRequest,
params: ExecuteParams,
) -> Result<RowStream>
```
Same as `execute` but scopes reads to nodes owned by `request` (used in thread-per-core deployments).
```rust
pub fn execute_fanout(
handles: Vec<&mut StorageHandle>,
params: ExecuteParams,
) -> Result<FanoutShardExecution>
```
Executes the same query across multiple shards and merges results. Returns a `FanoutShardExecution` that aggregates rows and per-shard `RowStream` metadata.
---
## ExecuteParams
```rust
pub struct ExecuteParams {
pub scan_start: u64, // inclusive lower bound of node ID range
pub scan_end_exclusive: u64, // exclusive upper bound
pub morsel_size: usize, // nodes processed per morsel (default: 256)
pub parallel_workers: usize, // 0 = single-threaded (default)
}
impl Default for ExecuteParams {
// scan_start: 0, scan_end_exclusive: 4096, morsel_size: 256, parallel_workers: 0
}
```
---
## Results
```rust
pub struct RowStream {
pub rows: Vec<Row>,
pub scanned_nodes: u64,
pub latency_micros: u128,
pub morsels_processed: u64,
pub rerank_batches: u64,
pub parallel_workers: usize,
}
impl RowStream {
pub fn to_json_pretty(&self) -> String
}
pub struct Row {
pub node_id: u64,
pub has_full: bool,
pub delta_count: usize,
pub adjacency_degree: usize,
pub score: Option<f64>, // set for vector queries; None for graph-only queries
}
```
```rust
pub struct FanoutShardExecution {
// Aggregated results from all shards
}
```
---
## Planning & Explain
```rust
pub fn explain(query: &str) -> Result<ExplainPlan>
```
Parses `query`, runs the planner, and returns a human-readable plan without executing anything.
```rust
pub struct ExplainPlan {
pub strategy: String,
pub planner_mode: String,
pub stats_version: Option<u64>,
pub logical_ops: Vec<String>,
pub physical_ops: Vec<PhysicalOp>,
pub estimated_cost: u64,
pub limit: Option<u64>,
pub predicate: Option<ExecutablePredicate>,
pub bitmap_predicate: Option<ExecutableBitmapPredicate>,
}
impl ExplainPlan {
pub fn to_json_pretty(&self) -> String
}
```
---
## Physical Operators
```rust
pub enum PhysicalOp {
BitmapScan, // driven by a roaring bitmap posting list
VectorScan, // ANN search: uses a matching per-space HNSW graph when uniquely identified, else brute-force scan
NodeScan, // sequential scan of node ID range
Filter, // score threshold filter
Project, // column projection
Limit, // result count limit
}
```
`VectorScan` uses ANN only when runtime can identify exactly one compatible vector space for the query's metric and inline-vector dimension. When no unique ANN-eligible space exists, or no graph is populated for that space, execution falls back to the full decoded vector scan/rerank path.
---
## Predicates
```rust
pub struct ExecutablePredicate {
pub param: String, // query parameter name
pub operator: String, // e.g. ">" or "<"
pub threshold: f64,
}
pub struct ExecutableBitmapPredicate {
pub index_name: String,
pub value_key: String,
}
```
---
## Planner Statistics
The planner can be seeded with collected statistics to enable cost-based plan selection.
```rust
pub fn planner_stats_snapshot() -> PlannerStatsSnapshot
pub fn set_planner_stats(enabled: bool)
pub fn clear_planner_stats()
pub struct PlannerStatsSnapshot {
pub schema_version: u32,
pub stats_version: u64,
pub collected_at_millis: u64,
pub ttl_millis: u64,
pub node_scan_base_cost: u64,
pub vector_scan_base_cost: u64,
pub filter_base_cost: u64,
pub vector_selectivity_ppm: u32,
pub graph_selectivity_ppm: u32,
pub skew_penalty_cost: u64,
}
```
---
## Errors
```rust
pub enum ExplainError {
InvalidPlan(String),
}
pub type Result<T> = std::result::Result<T, ExplainError>;
```