ELIPS exposes two Python surfaces over the same C++ core. The low-level bindings mirror C++ 1:1; the modern wrapper adds a typed, text-first surface around RecordInput, Row, and Hit.

open / connect

elips.open

Python

elips.open(path: str, *, dimension: int, metric: str = "cosine", index: str = "graph", access_mode: str = "read_write", use_default_text_embedder: bool = True) -> Database

C++

elips::open(std::string path, elips::Config cfg) -> std::unique_ptr<ElipsInstance>

elips.connect (modern)

Python

elips.connect(path: str, *, dimension: int, metric: str = "cosine", embedder: Callable | None = None) -> Engine

open takes durable identity (dimension, metric, index) plus runtime config (access mode, embedders). connect wraps open with the modern Engine.

Engine / Database

Database.vault

Python

db.vault(name: str) -> Vault

C++

ElipsInstance::vault(std::string name) -> Vault&

Database.query

Python

db.query(eql: str, *, bindings: dict | None = None) -> list[Row]

C++

ElipsInstance::query(std::string eql, std::map<std::string, Vector> bindings) -> std::vector<Row>

Database.begin_transaction

Python

db.begin_transaction() -> Transaction

C++

ElipsInstance::begin_transaction() -> Transaction

Database.checkpoint / compact / close

Python

db.checkpoint(); db.compact(); db.close()

C++

db->checkpoint(); db->compact(); db->close();

Vault / Arena

python

# low-level
docs.place(vector, payload, *, document=None, chunk=None, lineage=None)
docs.place_document(text, payload, *, lineage=None)
docs.erase(record_id)
docs.fetch(record_id) -> Record | None
docs.scan(*, where=None, offset=0, limit=None) -> list[Record]
docs.seek(vector, top=10, *, where=None, threshold=None) -> list[SearchResult]
docs.seek_text(text, top=10, *, where=None) -> list[SearchResult]
docs.seek_hybrid(vector, text, top=10, *, where=None) -> list[SearchResult]
docs.explain_seek(vector, top=10, *, where=None, has_text_component=False) -> QueryPlan
docs.rebuild_index()

python

# modern wrapper (Arena)
arena.write_many(records: list[RecordInput | dict]) -> list[RecordKey]
arena.pull(keys: list[RecordKey], *, include_vectors: bool = False) -> list[Row]
arena.probe(vector, top=10, *, where=None) -> list[Hit]
arena.probe_text(text, top=10, *, where=None) -> list[Hit]
arena.probe_hybrid(vector, text, top=10, *, where=None) -> list[Hit]
arena.ingest(texts=[...], meta=[...])  # legacy column shape

Filter

python

f = (elips.Filter()
     .field("kind").equals("design")
     .and_().field("year").greater_than(2023)
     .or_().field("country").is_in(["US", "GB", "CA"]))

Comparators: equals, not_equals, less_than, less_or_equal, greater_than, greater_or_equal, is_in, contains. Boolean combinators: and_, or_, not_.

QueryPlan

Field	Meaning
`strategy`	`ann_index` · `exact_candidates` · `full_scan` · `text_probe` · `hybrid_fusion`
`metadata_accelerated`	Whether the planner narrowed via `MetadataIndex`.
`candidate_count`	Candidate set size when narrowed.
`has_text_component`	Whether the plan includes a text stage.

Types

DocumentAttachment(text, uri=None, mime=None, attributes=)
ChunkInfo(document_key, position, length, attributes=)
EmbeddingLineage(provider, model, revision, attributes=)
SearchResult(id, distance, payload, document?, chunk?, lineage?)
RecordInput(text=..., vector=..., meta=..., document=..., chunk=..., lineage=...)
Hit(key, distance, text, meta, vector?, document?)

Errors

All runtime errors derive from ElipsError:

DimensionMismatch — vector width disagrees with identity.
InvalidVector — NaN, empty, or otherwise malformed input.
ConfigError — incompatible config or missing embedder on reopen.
StorageError — write attempted on a read-only handle, or persistence layer failure.
LockConflict — another writer holds the database.
NotFound — record id absent.