Rust SDK (embedded)

The namidb crate is the public façade of the engine: it re-exports the stable surface of namidb-core, namidb-storage, namidb-graph, and namidb-query so downstream code only needs one line.

Add it

[dependencies]
namidb = "0.3"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

MSRV is Rust 1.85.

Open a namespace

use namidb::storage::{parse_uri, WriterSession};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (store, paths) = parse_uri("s3://my-bucket?ns=prod&region=us-east-1")?;
    let mut writer = WriterSession::open(store, paths).await?;

    // ... upserts, commit_batch, snapshot reads ...

    Ok(())
}

Any URI scheme works: memory://, file://, s3://, gs://, az://.

Run Cypher

use namidb_query::{execute, lower, parse, Params};

let query = parse(
    "MATCH (a:Person) WHERE a.age > $min RETURN a.name AS name"
)?;
let plan = lower(&query)?;

let snap   = writer.snapshot();
let params = Params::from_iter([("min", 18.into())]);
let rows   = execute(&plan, &snap, &params).await?;

println!("{rows:?}");

Direct write API

For the highest-throughput ingestion path (bypassing the parser):

use namidb_core::id::{NodeId, EdgeType, Label};
use namidb_core::value::Value;

let alice = NodeId::generate_v7();
let bob   = NodeId::generate_v7();

writer.upsert_node(Label::new("Person"), alice, [
    ("name", Value::String("Alice".into())),
    ("age",  Value::Integer(30)),
].into())?;

writer.upsert_node(Label::new("Person"), bob, [
    ("name", Value::String("Bob".into())),
].into())?;

writer.upsert_edge(
    EdgeType::new("KNOWS"),
    alice,
    bob,
    [("since", Value::Integer(2020))].into(),
)?;

writer.commit_batch().await?;   // WAL append + manifest CAS
writer.flush().await?;          // memtable -> L0 SSTs

Snapshots

let snap_a = writer.snapshot();
// ... writes happen, manifest advances ...
let snap_b = writer.snapshot();
// snap_a still references the older manifest; both are valid.

Snapshots are cheap: they pin a manifest version and the SSTs it references. The GC won’t reclaim SSTs while any snapshot holds them.

Cache configuration

Env var	Default	Cache
`NAMIDB_ADJACENCY`	ON	CSR adjacency (RFC-018)
`NAMIDB_NODE_CACHE`	ON	`NodeView` lookups (RFC-019)
`NAMIDB_SST_CACHE`	ON	SST body + edge property streams (RFC-020)
`NAMIDB_FACTORIZE`	OFF	Factorized executor (RFC-017)

Crate layout

Crate	Surface
`namidb`	Public façade (re-exports the stable bits of the others)
`namidb-core`	`NamespaceId`, `NodeId`, `EdgeId`, `Lsn`, `Value`, `Schema`, errors
`namidb-storage`	LSM, WAL, manifest, SST, memtable, URI parser, `file://` CAS
`namidb-graph`	Property columns + CSR adjacency
`namidb-query`	Cypher / GQL parser, optimizer, executor

For day-to-day use, depend on namidb only. Reach for the sub-crates when you’re embedding deep (e.g. writing custom optimizer rules).