Rust crates
Crates
| Crate | Role |
|---|---|
namidb-core | Shared types: ids, schema, errors |
namidb-storage | URI parsing, writer and reader sessions, WAL, manifest commits, data files, flush, compaction, backup |
namidb-query | Cypher parser, planner, optimizer and executor |
namidb-graph | Graph algorithm kernels |
namidb-markdown | Markdown vault ingestion and embedders |
namidb-bolt | Bolt protocol (PackStream, handshake, session state machine) |
namidb-server, namidb-cli, namidb-mcp | The binaries |
namidb | Façade; currently re-exports namidb-core only |
[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" }Opening a namespace
use namidb_storage::{parse_uri, ReaderSession, WriterSession};
let (store, paths) = parse_uri("file:///var/lib/namidb?ns=prod")?;let mut writer = WriterSession::open(store.clone(), paths.clone()).await?;| Item | Purpose |
|---|---|
parse_uri(uri) -> (Arc<dyn ObjectStore>, NamespacePaths) | Same grammar as every other entry point (Storage URIs). |
parse_store(uri) | The store only, without requiring ?ns=. |
WriterSession::open(store, paths) | Open (or create) a namespace as its writer. Fences any previous writer. |
ReaderSession::open(store, paths, cache) | Open an existing namespace read-only, without claiming it; refresh() advances to the newest commit. |
Running Cypher
| Function | Purpose |
|---|---|
parse(src) -> Query | Parse one statement. |
plan(&query, &catalog) -> LogicalPlan | Lower and optimize. Build the catalog with StatsCatalog::from_manifest(&writer.snapshot().manifest().manifest). |
LogicalPlan::contains_write() | Whether the plan writes. |
execute(&plan, &snapshot, ¶ms) -> Vec<Row> | Run a read on a snapshot (writer.snapshot()). |
execute_write(&plan, &mut writer, ¶ms) -> WriteOutcome | Run a write and commit it before returning; on error the staged batch is discarded. |
execute_write_with_deadline(…, deadline) | The same with a deadline covering execution and commit. |
explain_query(…), explain_plan_lines(…) | Render plans like EXPLAIN. |
show_constraints_rows, show_indexes_rows | Rows for SHOW CONSTRAINTS / SHOW INDEXES. |
Params is a BTreeMap<String, RuntimeValue>. Row holds a
bindings: BTreeMap<String, RuntimeValue>; use output_columns(&plan) for
the RETURN order. WriteOutcome carries nodes_created,
edges_created, nodes_deleted, edges_deleted, properties_set and the
returned rows.
RuntimeValue variants: Null, Bool, Integer(i64), Float(f64),
String, Bytes, Vector(Vec<f32>), List, Map, Date (days since the
epoch), DateTime (UTC microseconds), Node, Rel, Path.
Writing without Cypher
WriterSession stages records directly; commit_batch() makes them
durable:
| Method | Purpose |
|---|---|
upsert_node(label, id, &NodeWriteRecord) / upsert_node_with_labels(labels, id, &record) | Stage a node. |
upsert_edge(edge_type, src, dst, &EdgeWriteRecord) | Stage a relationship. |
tombstone_node(label, id), tombstone_edge(edge_type, src, dst) | Stage deletions. |
commit_batch() | WAL append + manifest commit. |
discard_batch() | Drop staged records. |
Schema
DDL statements are intercepted before planning by the server and the CLI. In Rust call the methods directly:
| Method | DDL equivalent |
|---|---|
create_unique_constraint_named(name, label, &properties, if_not_exists) (one property or a composite tuple) | CREATE CONSTRAINT … IS UNIQUE |
create_property_index_named(…), create_composite_index_named(…) | CREATE INDEX |
register_vector_index(…), drop_vector_index(name, if_exists) | CREATE / DROP VECTOR INDEX (feature vector-index) |
register_text_index(…), drop_text_index(name, if_exists) | CREATE FULLTEXT INDEX / DROP INDEX (feature text-index) |
The Query returned by parse exposes as_create_constraint(),
as_create_index(), as_create_vector_index(),
as_create_fulltext_index() and as_show_schema() to detect these
statements and read their clauses.
Maintenance
| Method or function | Purpose |
|---|---|
WriterSession::flush(schema) | Write the memtable to L0 files. |
WriterSession::maybe_flush(max_wal_segments) | Flush only when the WAL has grown past a bound. |
WriterSession::compact_l0(&schema) | Compact level 0. |
sweep_orphans(…) | Delete unreferenced objects (the janitor’s sweep). |
copy_namespace_snapshot(…) | The consistent snapshot copy behind namidb backup / restore. |
Environment
The engine reads its cache, spool and search settings from the environment
when it first needs them (NAMIDB_CACHE_MAX_BYTES, NAMIDB_SPOOL_DIR,
…); see the configuration reference.
Embedded programs that want the server’s fail-fast validation of those
values can call namidb_storage::validate_cache_configuration() at
startup.