Skip to content

Embedded (Rust)

Dependencies

Depend on the storage and query crates at an exact tag:

[dependencies]
namidb-storage = { git = "https://github.com/namidb/namidb", tag = "v3.3.0" }
namidb-query = { git = "https://github.com/namidb/namidb", tag = "v3.3.0" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
anyhow = "1"

Rust 1.85 or newer is required. The namidb façade crate currently re-exports only the pure-data types of namidb-core (schema, ids); it is not yet an embedded-engine API.

Optional Cargo features, off by default:

Feature (on both namidb-query and namidb-storage)Enables
vector-indexBuilding and using persistent vector indexes
text-indexBuilding and using persistent full-text indexes

A complete program

This program opens a namespace, writes and reads with Cypher, and flushes. It was compiled and run against v3.2.1 as shown; v3.3.0 only adds to these crates’ API:

use namidb_query::{execute, execute_write, parse, plan, Params, RuntimeValue, StatsCatalog};
use namidb_storage::{parse_uri, WriterSession};
/// Parse, plan and run one Cypher statement. Writes are committed
/// (WAL append + manifest CAS) before `execute_write` returns.
async fn cypher(writer: &mut WriterSession, src: &str, params: &Params) -> anyhow::Result<()> {
let query = parse(src).map_err(|e| anyhow::anyhow!("{e:?}"))?;
let catalog = StatsCatalog::from_manifest(&writer.snapshot().manifest().manifest);
let plan = plan(&query, &catalog)?;
if plan.contains_write() {
let outcome = execute_write(&plan, writer, params).await?;
println!("nodes created: {}", outcome.nodes_created);
} else {
let snapshot = writer.snapshot();
for row in execute(&plan, &snapshot, params).await? {
println!("{:?}", row.bindings);
}
}
Ok(())
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Or file:///var/lib/namidb?ns=prod, s3://bucket?ns=prod, gs://…, az://…
let (store, paths) = parse_uri("memory://demo")?;
let mut writer = WriterSession::open(store, paths).await?;
let none = Params::new();
cypher(&mut writer, "CREATE (:Person {name: 'Alice', age: 30})", &none).await?;
cypher(&mut writer, "CREATE (:Person {name: 'Bob', age: 25})", &none).await?;
let mut params = Params::new();
params.insert("min".into(), RuntimeValue::Integer(18));
cypher(
&mut writer,
"MATCH (p:Person) WHERE p.age >= $min RETURN p.name AS name ORDER BY name",
&params,
)
.await?;
// Push the memtable into L0 SSTs (the server does this on a timer).
let schema = writer.schema().clone();
writer.flush(schema).await?;
Ok(())
}

Output:

nodes created: 1
nodes created: 1
{"name": String("Alice")}
{"name": String("Bob")}

What you take on

Embedding the crates gives you the engine without the conveniences the server and the Python client add:

  • Maintenance. Nothing flushes, compacts or sweeps on its own. Call WriterSession::flush regularly and run compaction (WriterSession::compact_l0) after loads.
  • Schema DDL. CREATE CONSTRAINT, CREATE INDEX, CREATE VECTOR INDEX and friends are not lowered to query plans; the server and CLI intercept them. In Rust call the schema methods on WriterSession (create_unique_constraint_named, create_property_index_named, create_composite_index_named, register_vector_index, register_text_index, drop_vector_index, drop_text_index).
  • Limits. No query timeout, row cap or memory governor unless you add them (execute_write_with_deadline accepts a deadline).
  • One writer per namespace. WriterSession::open claims the namespace and fences any other writer, exactly like the other entry points.

The API reference is on the Rust library page.