Custom embedders

Two paths exist. The rehydratable local embedder is persisted via TEXT_EMBEDDER.manifest and reattached automatically. A Python callable embedder is metadata-only — reopening without the same callable raises ConfigError.

python

def my_embedder(texts: list[str]) -> list[list[float]]:
    return model.encode(texts).tolist()

db = elips.open_with_config(
    "/tmp/elips",
    elips.Config()
        .dimension(384)
        .metric("cosine")
        .text_embedder(my_embedder, provider="myco", model="bge-small", revision="v1"),
)

Planner introspection

explain_seek returns the strategy the planner chose, whether MetadataIndex narrowed the search, and the candidate count when narrowing occurred. Use it in tests to lock query shapes against accidental regressions.

python

plan = docs.explain_seek(
    [1.0, 0.0],
    top=5,
    where=elips.Filter().field("kind").equals("design"),
    has_text_component=True,
)
assert plan.metadata_accelerated
assert plan.strategy in {"exact_candidates", "hybrid_fusion"}

Transactions

Transactions buffer place and erase in memory and commit atomically.

cpp

auto txn = db->begin_transaction();
txn.vault("documents").place(elips::Vector{{1.0F, 0.0F}});
txn.vault("documents").place(elips::Vector{{0.0F, 1.0F}});
txn.commit();   // both visible or neither

Lineage & migration

EmbeddingLineage records the provider, model, and revision that produced each vector. When you migrate to a new embedder, you can filter on lineage to re-embed only the records that need it.

python

stale = docs.scan(where=elips.Filter()
                  .field("__lineage.model").equals("bge-small"))
for r in stale:
    docs.erase(r.id)
    docs.place_document(r.document.text, r.payload,
                        lineage=elips.EmbeddingLineage("myco", "bge-large", "v2"))

Recovery testing

abandon() closes the database without checkpointing, leaving unfinished recovery work in the WAL. Pair it with elips verify in integration tests to assert recovery semantics across crash points.