Settings are passed as keyword arguments to elips.Client / elips.PersistentClient (the native Config builder mirrors them in C++). A subset of these values become the durable identity of the database, persisted in the IDENTITY file, and cannot change after first open.

Identity (frozen at first open)

Three values are durable: dimension, metric, and index. Reopening with a conflicting value raises ConfigError.

python

db = elips.PersistentClient(
    "/var/lib/myapp/elips",
    dimension=384,
    metric="cosine",       # "cosine" | "euclidean" | "dot_product"
    index="graph",         # "graph" (HNSW) | "exact" (flat)
)

Indexes

graph is the default — a Hierarchical Navigable Small World graph backed by IndexHNSW. exact performs a brute-force scan (IndexFlat) and is suitable for small collections, test workloads, and ground-truth measurement. Both implement the same Index contract; see Algorithms.

cpp

auto db = elips::open(
    "/tmp/elips",
    elips::Config{}
        .dimension(128)
        .metric(elips::Metric::cosine)
        .hnsw_params({.M = 16, .ef_construction = 200, .ef_search = 64}));

Durability

Durability is a native Config / Durability setting — it is not a Client keyword argument. It controls when WAL appends reach disk:

Mode	Behaviour
`paranoid`	Flush and `fsync` on every WAL append.
`standard`	Flush on every append.
`relaxed`	Buffer; flush at checkpoint and close.
`ephemeral`	No WAL is attached. In-memory only.

Persistence

Segmented storage is on by default. Disable it with Config::segmented_storage(false) to fall back to the single-file elips.snapshot format. Both formats are crash-safe; Storage & recovery walks the on-disk layout.

Embedders

New databases auto-attach the built-in local text embedder. Two explicit choices are supported:

Config.local_text_embedder(...) — a rehydratable local embedder. ELIPS restores it automatically on reopen via TEXT_EMBEDDER.manifest and a deterministic artifact.
Config.text_embedder(callable, ...) — a Python callable. Metadata is persisted, but reopening without providing the same callable causes text-first APIs to raise ConfigError rather than silently degrading.

Access mode

read_write takes an exclusive advisory lock — one writer per database. read_only takes a shared lock and rejects every mutation path with StorageError. Use read-only mode for shared-reader analytics or fan-out serving.

python

reader = elips.PersistentClient("/var/lib/myapp/elips", access_mode="read_only")
docs = reader.get_collection("documents")
print(docs.query(query_texts="alpha", n_results=1)[0].meta)