Struct Engine 

pub struct Engine {
    pub store: NodeStore,
    pub catalog: Catalog,
    pub csrs: HashMap<u32, CsrForward>,
    pub db_root: PathBuf,
    pub params: HashMap<String, Value>,
    pub prop_index: PropertyIndex,
    pub text_index: TextIndex,
    pub deadline: Option<Instant>,
}

The execution engine holds references to the storage layer.

Fields

store: NodeStore

catalog: Catalog

csrs: HashMap<u32, CsrForward>

Per-relationship-type CSR forward files, keyed by RelTableId (u32). Replaces the old single csr: CsrForward field so that different relationship types use separate edge tables (SPA-185).

db_root: PathBuf

params: HashMap<String, Value>

Runtime query parameters supplied by the caller (e.g. $name → Value).

prop_index: PropertyIndex

In-memory B-tree property equality index (SPA-249).

Built at Engine::new time by scanning all on-disk column files. Enables O(log n) equality-filter scans instead of O(n) full scans.

text_index: TextIndex

In-memory text search index for CONTAINS and STARTS WITH (SPA-251).

Built at Engine::new alongside prop_index. Stores sorted (decoded_string, slot) pairs per (label_id, col_id).

• CONTAINS: linear scan avoids per-slot property-decode overhead.
• STARTS WITH: binary-search prefix range — O(log n + k).

deadline: Option<Instant>

Optional per-query deadline (SPA-254).

When Some, the engine checks this deadline at the top of each hot scan / traversal loop iteration. If Instant::now() >= deadline, Error::QueryTimeout is returned immediately. None means no deadline (backward-compatible default).

Implementations

impl Engine

pub fn new( store: NodeStore, catalog: Catalog, csrs: HashMap<u32, CsrForward>, db_root: &Path, ) -> Self

Create an engine with a pre-built per-type CSR map.

The csrs map associates each RelTableId (u32) with its forward CSR. Use Engine::with_single_csr in tests or legacy code that only has one CSR.

pub fn with_single_csr( store: NodeStore, catalog: Catalog, csr: CsrForward, db_root: &Path, ) -> Self

Convenience constructor for tests and legacy callers that have a single CsrForward (stored at RelTableId(0)).

SPA-185: prefer Engine::new with a full HashMap<u32, CsrForward> for production use so that per-type filtering is correct.

pub fn with_params(self, params: HashMap<String, Value>) -> Self

Attach runtime query parameters to this engine instance.

Parameters are looked up when evaluating $name expressions (e.g. in UNWIND $items AS x).

pub fn with_deadline(self, deadline: Instant) -> Self

Set a per-query deadline (SPA-254).

The engine will return sparrowdb_common::Error::QueryTimeout if Instant::now() >= deadline during any hot scan or traversal loop.

pub fn execute(&mut self, cypher: &str) -> Result<QueryResult>

Parse, bind, plan, and execute a Cypher query.

Takes &mut self because CREATE statements auto-register labels in the catalog and write nodes to the node store (SPA-156).

pub fn execute_statement(&mut self, stmt: Statement) -> Result<QueryResult>

Execute an already-bound Statement directly.

Useful for callers (e.g. WriteTx) that have already parsed and bound the statement and want to dispatch CHECKPOINT/OPTIMIZE themselves.

pub fn is_mutation(stmt: &Statement) -> bool

Returns true if stmt is a mutation (MERGE, MATCH+SET, MATCH+DELETE, MATCH+CREATE edge).

Used by GraphDb::execute to route the statement to the write path.

pub fn scan_match_mutate( &self, mm: &MatchMutateStatement, ) -> Result<Vec<NodeId>>

Scan nodes matching the MATCH patterns in a MatchMutate statement and return the list of matching NodeIds. The caller is responsible for applying the actual mutations inside a write transaction.

pub fn mutation_from_match_mutate(mm: &MatchMutateStatement) -> &Mutation

Return the mutation carried by a MatchMutate statement, exposing it to the caller (GraphDb) so it can apply it inside a write transaction.

pub fn scan_match_create( &self, mc: &MatchCreateStatement, ) -> Result<HashMap<String, Vec<NodeId>>>

Scan nodes matching the MATCH patterns in a MatchCreateStatement and return a map of variable name → Vec for each named node pattern.

The caller (GraphDb) uses this to resolve variable bindings before calling WriteTx::create_edge for each edge in the CREATE clause.

pub fn scan_match_create_rows( &self, mc: &MatchCreateStatement, ) -> Result<Vec<HashMap<String, NodeId>>>

Execute the MATCH portion of a MatchCreateStatement and return one binding map per matched row.

Each element of the returned Vec is a HashMap<variable_name, NodeId> that represents one fully-correlated result row from the MATCH clause. The caller uses these to drive WriteTx::create_edge — one call per row.

Algorithm

For each PathPattern in match_patterns:

• No relationships (node-only pattern): scan the node store applying inline prop filters; collect one candidate set per named variable. Cross-join these sets with the rows accumulated so far.
• One relationship hop ((a)-[:R]->(b)): traverse the CSR + delta log to enumerate actual (src, dst) pairs that are connected by an edge, then filter each node against its inline prop predicates. Only correlated pairs are yielded — this is the key difference from the old scan_match_create which treated every node as an independent candidate and then took a full Cartesian product.

Patterns beyond a single hop are not yet supported and return an error.

pub fn scan_match_merge_rel_rows( &self, mm: &MatchMergeRelStatement, ) -> Result<Vec<HashMap<String, NodeId>>>

Scan the MATCH patterns of a MatchMergeRelStatement and return correlated (variable → NodeId) binding rows — identical semantics to scan_match_create_rows but taking the MERGE form’s match patterns (SPA-233).