Struct CypherEngine 

pub struct CypherEngine { /* private fields */ }

Cypher query engine with a cached catalog for efficient multi-query execution.

The engine registers each dataset once and reuses the catalog and DataFusion context across queries.

Lance datasets are read lazily from storage, pinned to the version they were opened at: writes made later (by this or another process) are not visible until refresh. Each dataset is pinned separately; versions across tables are not a transactional multi-table snapshot. Arrow batches are held in memory and never change; build a new engine to replace them.

Building the CSR (use_csr) is CPU-bound work inside an async function: in an application with its own async runtime, construct and refresh the engine on a blocking thread (for example tokio::task::spawn_blocking plus block_on).

Implementations

impl CypherEngine

pub async fn new( config: GraphConfig, sources: HashMap<String, EngineSource>, use_csr: bool, ) -> Result<Self>

Register sources (dataset name -> data) and build the snapshot.

Lance datasets are not read here, except for the CSR, node-index and join-key statistics builds. With use_csr, relationship types with integer endpoints get CSR adjacencies and node labels with unique integer ids get a node index.

Errors

GraphError::ConfigError if sources is empty or a configured id/endpoint column is missing; GraphError::ExecutionError if a dataset cannot be registered or scanned.

pub async fn with_target_partitions( config: GraphConfig, sources: HashMap<String, EngineSource>, use_csr: bool, target_partitions: Option<usize>, ) -> Result<Self>

Like new, with a target for DataFusion query partitioning.

Some(n) sets DataFusion’s target_partitions for every query, kept across refresh; None keeps DataFusion’s default (the number of cores). It is not a thread or memory limit. In-memory Arrow inputs are still sliced into one partition per core.

Errors

As new, plus GraphError::ConfigError if target_partitions is outside 1..=1024.

pub async fn execute( &self, query: &str, params: HashMap<String, JsonValue>, ) -> Result<RecordBatch>

Execute a Cypher query and return the whole result as one batch.

params gives values for $name parameters in the query. Use execute_stream for large outputs.

pub async fn execute_stream( &self, query: &str, params: HashMap<String, JsonValue>, ) -> Result<SendableRecordBatchStream>

Execute a Cypher query and stream the result.

Batches are computed as the stream is polled. Scans, filters and projections stream with bounded memory; joins, sorts and aggregations may still buffer. The stream keeps what it reads alive, so a concurrent refresh() does not affect it. Planning errors return here; execution errors arrive in the stream. Dropping the stream cancels the remaining work.

pub async fn explain( &self, query: &str, params: HashMap<String, JsonValue>, ) -> Result<String>

Return the query plan, including the physical plan with pushed-down scans.

pub async fn execute_with_vector_rerank( &self, query: &str, vector_search: &VectorSearch, ) -> Result<RecordBatch>

Execute a Cypher query, then rerank its rows by vector similarity.

pub async fn refresh(&self) -> Result<()>

Move every Lance dataset to its latest version.

Datasets whose version and commit time are unchanged keep their open handle. The replacement is validated in full before it is swapped in; on error nothing changes and the previous snapshot stays usable. Queries already running finish on the snapshot they started with. Arrow inputs are unchanged. Concurrent calls run one at a time.

pub fn csr_stats(&self) -> HashMap<String, CsrStats>

CSR adjacency statistics per relationship type (experimental, use_csr).

An identical map after refresh() means the snapshot itself was unchanged.

pub fn node_index_stats(&self) -> HashMap<String, NodeIndexStats>

Node id -> row index statistics per node label (experimental, use_csr).

A label is missing when its ids are not unique integers; its targets then use a join.

pub fn dataset_versions(&self) -> HashMap<String, u64>

Pinned version of each Lance dataset, keyed by dataset name.

pub fn config(&self) -> &GraphConfig

The graph configuration the engine was built with.