Skip to content
NamiDB NamiDB

Caches

NamiDB ships three process-wide caches that share data across snapshots. All are Arc-shared and byte-budgeted.

CacheWhat it holdsRFCEnv var
AdjacencyCacheCSR adjacency arrays per edge SSTRFC-018NAMIDB_ADJACENCY
NodeViewCacheDecoded NodeView (id → label, props) lookupsRFC-019NAMIDB_NODE_CACHE
SstCacheDecoded SST body + edge property streams + parsed EdgeSstReaderRFC-020NAMIDB_SST_CACHE

All three default to ON. Set the env var to 0 or off to disable.

Why cross-snapshot

A long-running write workload produces a new manifest version on every commit. Without cross-snapshot caches, every snapshot transition would invalidate the entire cache and re-pay the decode cost.

NamiDB’s caches are keyed by the immutable SST id, not by the snapshot. As long as an SST is referenced by any live snapshot, its decoded artifacts stay in cache.

Sizing

The default budgets are tuned for a “comfortable laptop”: ~512 MiB per cache. For server workloads, bump them:

Terminal window
export NAMIDB_ADJACENCY_BUDGET_MB=4096
export NAMIDB_NODE_CACHE_BUDGET_MB=2048
export NAMIDB_SST_CACHE_BUDGET_MB=8192

For embedded use, you may want them smaller — they’re all eviction-bounded.

Observability

The Python client exposes:

print(client.cache_stats())
# {
#   "adjacency": {"hits": ..., "misses": ..., "bytes": ...},
#   "node_view": {...},
#   "sst":       {...}
# }

Hook this into your dashboards to spot working-set vs budget mismatches.

Hybrid cache (optional)

NamiDB embeds foyer for an optional memory + NVMe tier — keeps the hot working set in RAM and spills warm pages to local NVMe. Useful when bucket round-trips are slow (cross-region) or expensive (egress fees).

See also