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: RefCell<PropertyIndex>,
    pub text_index: RefCell<TextIndex>,
    pub deadline: Option<Instant>,
    pub degree_cache: DegreeCache,
    pub unique_constraints: HashSet<(u32, u32)>,
}

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: RefCell<PropertyIndex>

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

Loaded lazily on first use for each (label_id, col_id) pair that a query actually filters on. Queries with no property filter (e.g. COUNT(*), hop traversals) never touch this and pay zero build cost. RefCell provides interior mutability so that build_for can be called from &self scan helpers without changing every method signature.

text_index: RefCell<TextIndex>

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

Loaded lazily — only when a query has a CONTAINS or STARTS WITH predicate on a specific (label_id, col_id) pair, via TextIndex::build_for. Queries with no text predicates (e.g. COUNT(*), hop traversals) never trigger any TextIndex I/O. RefCell provides interior mutability so that build_for can be called from &self scan helpers without changing every method signature. 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).

degree_cache: DegreeCache

Pre-computed out-degree for every node slot across all relationship types (SPA-272).

Built eagerly in Engine::new by scanning all CSR forward files and all delta-log records. Provides O(1) degree lookup for Engine::top_k_by_degree.

unique_constraints: HashSet<(u32, u32)>

UNIQUE constraints: (label_id, col_id) pairs registered via CREATE CONSTRAINT.

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 top_k_by_degree( &self, label_id: u32, k: usize, ) -> Result<Vec<(u64, u32)>>

Return the top-k nodes of label_id ordered by out-degree descending.

Each element of the returned Vec is (slot, out_degree). Ties in degree are broken by slot number (lower slot first) for determinism.

Returns an empty Vec when k == 0 or the label has no nodes.

Uses DegreeCache for O(1) per-node lookups (SPA-272).

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).