Persistence¶

This guide shows how to save, load, and memory-map NphdIndex instances.

Save an index to disk¶

index.save("my_index.usearch")

This writes the full index (HNSW graph and vectors) to a single file.

Load an index from disk¶

load() reads the entire file into RAM:

from iscc_usearch import NphdIndex

index = NphdIndex()
index.load("my_index.usearch")

You can also use restore() to create and load in one step:

index = NphdIndex.restore("my_index.usearch")

Memory-map an index¶

view() memory-maps the file for read-only access. The OS pages data in on demand, so startup is fast and memory usage stays low:

index = NphdIndex.restore("my_index.usearch", view=True)

Or explicitly:

index = NphdIndex()
index.view("my_index.usearch")

Warning

A viewed index is read-only. Calling add() on a viewed index raises an error from USearch's C++ core.

Restore with auto-detect¶

NphdIndex.restore() calls either load() or view() based on the view parameter:

# Full load (default)
index = NphdIndex.restore("my_index.usearch")

# Memory-mapped
index = NphdIndex.restore("my_index.usearch", view=True)

Copy an index¶

copy() creates an independent in-memory clone with the same configuration and data:

copy = index.copy()

The copy is independent. Modifying one does not affect the other.

Choosing a method¶

Method	RAM usage	Startup speed	Writable	Use case
`load()`	High	Slower	Yes	Read-write workloads
`view()`	Low	Fast	No	Read-only serving, many shards
`restore()`	Either	Either	Either	Convenience dispatcher
`copy()`	High	Instant	Yes	Fork an index for experiments

Dirty counter¶

NphdIndex tracks unsaved mutations via the dirty property. It increments on each add() or remove() call and resets to 0 on save(), load(), view(), and reset():

index = NphdIndex(max_dim=256)
index.add(1, vec)
print(index.dirty)  # 1

index.save("my_index.usearch")
print(index.dirty)  # 0

Use dirty to implement caller-driven flush policies (e.g., "save every N writes").

Metric persistence¶

The native MetricKind.NPHD metric is correctly serialized and deserialized by usearch-iscc. No manual metric restoration is needed after load() or view() operations.