Skip to content

Python API reference

Terminal window
pip install namidb # Python >= 3.9; pyarrow >= 14 comes with it
import namidb
print(namidb.__version__) # 3.3.0

The 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,
)
ParameterMeaning
uriStorage URI with the namespace: memory://ns, file:///dir?ns=ns, s3://…, gs://…, az://…. See Storage URIs.
cache_bytesSize of this client’s SST cache, reported by cache_stats(). Default 64 MiB. Process-wide caches are sized by NAMIDB_CACHE_MAX_BYTES.
read_onlyOpen without claiming the namespace; every mutator raises PermissionError. The namespace must exist.
spool_dirScratch directory for compaction. Defaults to NAMIDB_SPOOL_DIR, then <root>/.namidb-spool for file://, else /var/tmp.
auto_sweep_min_age_secsAfter an applied compaction, delete unreferenced objects older than this. None disables the automatic sweep.
compaction_l0_triggerflush() 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

MethodReturns
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.
  • params is a dict[str, Any]; see type mapping.
  • timeout_ms bounds the whole call, including waiting for the client’s write lock; a timed-out write is discarded. Raises QueryTimeoutError.
  • max_rows fails a read as soon as any plan step produces more rows. Raises QueryRowCapError. Writes ignore it.
  • Syntax and planning errors raise ValueError; execution errors raise RuntimeError; writes on a read-only client raise PermissionError.
result = db.cypher(
"MATCH (p:Person) WHERE p.age > $min RETURN p.name AS name, p.age AS age",
params={"min": 26},
)

QueryResult

MemberReturns
columnsColumn 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) # 3
r.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.

MethodEffect
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") # 3
db.load_parquet_edges("LINK", "edges.parquet") # 2
db.commit()

Lookups and scans

These read committed data without Cypher.

MethodReturns
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

MethodEffect
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

ExceptionBaseRaised when
namidb.QueryTimeoutErrorTimeoutErrortimeout_ms elapsed
namidb.QueryRowCapErrorRuntimeErrormax_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.

CypherPython
NULLNone
BOOLEANbool (checked before int, so True never becomes 1)
INTEGERint
FLOATfloat
STRINGstr
BYTESbytes
LIST, VECTORlist (pass list[float] for vectors)
MAPdict[str, …]
DATEdatetime.date
DATETIMEdatetime.datetime, UTC
Node{'_kind': 'node', 'id', 'label', 'labels', 'properties'}
Relationship{'_kind': 'rel', 'edge_type', 'src', 'dst', 'properties'}
Pathlist 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 Client at once.
  • Writes are serialised per client.
  • One writer per namespace across processes: opening a writable Client fences any other writer of that namespace. Use read_only=True for additional readers.