Python API reference
pip install namidb # Python >= 3.9; pyarrow >= 14 comes with itimport namidbprint(namidb.__version__) # 3.3.0The package exports Client, QueryResult, NodeIter, EdgeIter,
QueryTimeoutError and QueryRowCapError. For deployment patterns
(durability, disk space, read-only clients, threads) see
Embedded Python.
Client
namidb.Client( uri, cache_bytes=None, *, read_only=False, spool_dir=None, auto_sweep_min_age_secs=60, compaction_l0_trigger=8,)| Parameter | Meaning |
|---|---|
uri | Storage URI with the namespace: memory://ns, file:///dir?ns=ns, s3://…, gs://…, az://…. See Storage URIs. |
cache_bytes | Size of this client’s SST cache, reported by cache_stats(). Default 64 MiB. Process-wide caches are sized by NAMIDB_CACHE_MAX_BYTES. |
read_only | Open without claiming the namespace; every mutator raises PermissionError. The namespace must exist. |
spool_dir | Scratch directory for compaction. Defaults to NAMIDB_SPOOL_DIR, then <root>/.namidb-spool for file://, else /var/tmp. |
auto_sweep_min_age_secs | After an applied compaction, delete unreferenced objects older than this. None disables the automatic sweep. |
compaction_l0_trigger | flush() compacts once a bucket holds this many level-0 files. 0 disables. |
A Client is also a context manager; leaving the with block calls
close().
Cypher
| Method | Returns |
|---|---|
cypher(query, params=None, *, timeout_ms=None, max_rows=None) | QueryResult |
acypher(query, params=None, *, timeout_ms=None, max_rows=None) | awaitable QueryResult |
- Writes and DDL are committed before the call returns.
paramsis adict[str, Any]; see type mapping.timeout_msbounds the whole call, including waiting for the client’s write lock; a timed-out write is discarded. RaisesQueryTimeoutError.max_rowsfails a read as soon as any plan step produces more rows. RaisesQueryRowCapError. Writes ignore it.- Syntax and planning errors raise
ValueError; execution errors raiseRuntimeError; writes on a read-only client raisePermissionError.
result = db.cypher( "MATCH (p:Person) WHERE p.age > $min RETURN p.name AS name, p.age AS age", params={"min": 26},)QueryResult
| Member | Returns |
|---|---|
columns | Column names in RETURN order (also for an empty result). |
rows() | list[dict], one dict per row. |
first() | The first row, or None. |
len(result) | Number of rows. |
to_arrow() | pyarrow.Table |
to_pandas() | pandas.DataFrame (needs namidb[pandas]) |
to_polars() | polars.DataFrame (needs namidb[polars]) |
r = db.cypher("MATCH (i:Item) RETURN i.name AS name ORDER BY name")r.columns # ['name']len(r) # 3r.first() # {'name': 'a'}r.to_pandas() # DataFrame with one column, 'name'Bulk loading
These methods stage changes into a pending batch. Call commit() to make
them durable. They skip Cypher parsing and planning, so they are the fast
path for large loads.
| Method | Effect |
|---|---|
put_nodes(label, rows) | Replace nodes. Each row is a dict with _id (UUID string) plus properties; the row is the node’s full property set and label its only label. No read first: fastest for first loads. Returns the staged count. |
merge_nodes(label, rows) | Merge into stored nodes: unmentioned keys are kept, a None value removes the key, label is added. Reads each node first. |
merge_edges(edge_type, rows) | Upsert relationships. Each row has src and dst UUID strings plus properties. |
upsert_node(label, id, properties) | Stage one node. |
upsert_node_with_labels(labels, id, properties) | Stage one node with a full label set. |
upsert_edge(edge_type, src, dst, properties) | Stage one relationship. |
tombstone_node(label, id) | Stage a node deletion. |
tombstone_edge(edge_type, src, dst) | Stage a relationship deletion. |
load_parquet_nodes(label, path, commit_every=0) | Load a Parquet file: a node_id column of 16-byte UUIDs (FixedSizeBinary(16) or 16-byte binary), every other column a property. Returns rows loaded. |
load_parquet_edges(edge_type, path, commit_every=0) | Load a Parquet file with src and dst 16-byte UUID columns; other columns are properties. Endpoints must exist. |
commit() | Commit the pending batch (WAL append + manifest commit). Returns the last LSN, or None for an empty batch. |
import uuid
alice, bob = str(uuid.uuid4()), str(uuid.uuid4())db.put_nodes("Person", [ {"_id": alice, "name": "Alice", "age": 30}, {"_id": bob, "name": "Bob"},])db.merge_edges("KNOWS", [{"src": alice, "dst": bob, "since": 2020}])db.commit()db.flush()_id is the node id, the same value as n._id and id(n) in Cypher; it is
not stored as a property, so a business key called id can sit next to it.
Rows keyed by id alone (the older form) still work: id becomes the node
id and is also kept as an id property.
With commit_every=N, the Parquet loaders commit every N rows; with 0
everything stays pending until you call commit().
import pyarrow as pa, pyarrow.parquet as pq
ids = [uuid.uuid4() for _ in range(3)]pq.write_table(pa.table({ "node_id": pa.array([u.bytes for u in ids], type=pa.binary(16)), "name": ["a", "b", "c"],}), "nodes.parquet")pq.write_table(pa.table({ "src": pa.array([ids[0].bytes, ids[1].bytes], type=pa.binary(16)), "dst": pa.array([ids[1].bytes, ids[2].bytes], type=pa.binary(16)), "w": [1.0, 2.0],}), "edges.parquet")
db.load_parquet_nodes("Item", "nodes.parquet") # 3db.load_parquet_edges("LINK", "edges.parquet") # 2db.commit()Lookups and scans
These read committed data without Cypher.
| Method | Returns |
|---|---|
lookup_node(label, id) | A node dict, or None |
out_edges(edge_type, src), in_edges(edge_type, dst) | List of edge dicts |
scan_label(label, limit=None) | List of node dicts |
scan_label_arrow(label, limit=None) | pyarrow.Table with id, label, labels, lsn, schema_version and one column per property key |
iter_label(label, limit=None) | A lazy NodeIter, 1,024 nodes per step |
scan_edge_type(edge_type, limit=None) | List of edge dicts |
iter_edge_type(edge_type, limit=None) | A lazy EdgeIter |
db.lookup_node("Person", alice)# {'id': '…', 'label': 'Person', 'labels': ['Person'], 'lsn': 1,# 'schema_version': 0, 'properties': {'age': 30, 'name': 'Alice'}}
db.out_edges("KNOWS", alice)# [{'edge_type': 'KNOWS', 'src': '…', 'dst': '…', 'lsn': 3,# 'properties': {'since': 2020}}]An iterator reads every row from the version that was current when it was created, even while writes and compactions continue, and keeps that version’s files alive until it is dropped. If a step raises, the iterator is finished.
Maintenance
| Method | Effect |
|---|---|
flush() | Write the in-memory table to level-0 files; then compact if a bucket reached compaction_l0_trigger. |
compact() / acompact() | Run one compaction pass. Returns a dict: applied, l0_before, l0_after, source_ssts_removed, new_ssts_written, bloom_sidecars_written, manifest_version_before, manifest_version_after. |
sweep(min_age_secs=60, dry_run=False) | Delete unreferenced objects older than min_age_secs. Returns counts (orphans_deleted, bytes_freed, wal_segments_reclaimed, manifest_snapshots_reclaimed, …, aborted_by_pin). |
refresh() | Read-only clients: move to the newest commit; True if it advanced. A no-op (False) on a writer. |
close() | Read-only clients: release the retention lease now. The client keeps working. |
cache_stats() | (hits, misses, inserts, usage_bytes) of this client’s SST cache. |
load_vault(path, label="Note", edge_type="LINKS_TO", commit_every=1000, prune=False, placeholders=False) | Load a Markdown vault (see CLI); commits before returning and returns load statistics. |
If aborted_by_pin is True in a sweep report, a reader’s lease appeared
mid-sweep and nothing was deleted; run the sweep again.
Exceptions
| Exception | Base | Raised when |
|---|---|---|
namidb.QueryTimeoutError | TimeoutError | timeout_ms elapsed |
namidb.QueryRowCapError | RuntimeError | max_rows exceeded |
ValueError | — | Invalid URI or namespace, Cypher syntax or planning error |
RuntimeError | — | Execution or storage error, constraint violation |
PermissionError | — | A mutating call on a read_only=True client |
Type mapping
Parameters and results use the same mapping.
| Cypher | Python |
|---|---|
NULL | None |
BOOLEAN | bool (checked before int, so True never becomes 1) |
INTEGER | int |
FLOAT | float |
STRING | str |
BYTES | bytes |
LIST, VECTOR | list (pass list[float] for vectors) |
MAP | dict[str, …] |
DATE | datetime.date |
DATETIME | datetime.datetime, UTC |
| Node | {'_kind': 'node', 'id', 'label', 'labels', 'properties'} |
| Relationship | {'_kind': 'rel', 'edge_type', 'src', 'dst', 'properties'} |
| Path | list alternating node and relationship dicts |
Concurrency
- Every blocking call releases the GIL.
- Reads run on the latest committed snapshot without the writer lock; many
threads can read one
Clientat once. - Writes are serialised per client.
- One writer per namespace across processes: opening a writable
Clientfences any other writer of that namespace. Useread_only=Truefor additional readers.