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-index | Building and using persistent vector indexes |
text-index | Building 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", ¶ms, ) .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: 1nodes 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::flushregularly and run compaction (WriterSession::compact_l0) after loads. - Schema DDL.
CREATE CONSTRAINT,CREATE INDEX,CREATE VECTOR INDEXand friends are not lowered to query plans; the server and CLI intercept them. In Rust call the schema methods onWriterSession(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_deadlineaccepts a deadline). - One writer per namespace.
WriterSession::openclaims the namespace and fences any other writer, exactly like the other entry points.
The API reference is on the Rust library page.