Skip to content

Rust crates

Crates

CrateRole
namidb-coreShared types: ids, schema, errors
namidb-storageURI parsing, writer and reader sessions, WAL, manifest commits, data files, flush, compaction, backup
namidb-queryCypher parser, planner, optimizer and executor
namidb-graphGraph algorithm kernels
namidb-markdownMarkdown vault ingestion and embedders
namidb-boltBolt protocol (PackStream, handshake, session state machine)
namidb-server, namidb-cli, namidb-mcpThe binaries
namidbFaç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?;
ItemPurpose
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

FunctionPurpose
parse(src) -> QueryParse one statement.
plan(&query, &catalog) -> LogicalPlanLower and optimize. Build the catalog with StatsCatalog::from_manifest(&writer.snapshot().manifest().manifest).
LogicalPlan::contains_write()Whether the plan writes.
execute(&plan, &snapshot, &params) -> Vec<Row>Run a read on a snapshot (writer.snapshot()).
execute_write(&plan, &mut writer, &params) -> WriteOutcomeRun 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_rowsRows 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:

MethodPurpose
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:

MethodDDL 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 functionPurpose
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.