ELIPS is implemented as a header-first C++23 library designed for embedded vector storage, zero-copy graph traversals, and hardware-accelerated hybrid search. The native C++ API provides direct, un-sandboxed access to all engine primitives.

Overview

The native C++ API is optimized for high-throughput, low-latency applications where language binding overhead cannot be tolerated. Built with modern C++23, it relies on RAII ownership, move semantics, std::shared_mutex for concurrent reads, and zero-allocation query execution paths wherever possible.

Header Structure

All public C++ headers reside under the elips/ include path. Including <elips/elips.hpp> pulls in the full surface area of the engine.

cpp

// Master header providing ElipsInstance, Vault, Transaction, and Domain types
#include <elips/elips.hpp>

// Specific subsystem headers (included automatically by elips.hpp)
#include <elips/Config.hpp>
#include <elips/domain/Record.hpp>
#include <elips/domain/SearchResult.hpp>
#include <elips/domain/Vector.hpp>
#include <elips/metadata/Filter.hpp>

Core Abstractions

The C++ surface is organized around five primary classes:

elips::ElipsInstance — Top-level database handle managing storage, WAL, locking, and multi-vault registries.
elips::Vault — A named partition owning vector graph indices, metadata inverted indices, and record stores.
elips::Record & Vector — Domain primitives representing vectors, payloads, and search results.
elips::Config — Fluent configuration specifying dimensions, distance metrics, HNSW parameters, and durability policies.
elips::Transaction — Multi-vault atomic transactional write batching with automatic rollback capability.

Memory & RAII Semantics

All resource ownership in ELIPS C++ API strictly follows Resource Acquisition Is Initialization (RAII).

elips::open() returns a std::unique_ptr<ElipsInstance>.
When ElipsInstance is destroyed, it flushes pending WAL logs, executes a database checkpoint (for persistent databases), and releases file lock handles.
Vault objects are owned by their parent ElipsInstance and returned by reference.

Concurrency & Thread Safety

ELIPS enforces multi-level concurrency protection:

Process Isolation: An advisory flock lock manager prevents multiple processes from opening the same disk database in Read-Write mode simultaneously.
Thread Safety: ElipsInstance uses a recursive mutex for vault registry lookups. Each Vault contains a std::shared_mutex allowing arbitrary concurrent readers (e.g. seek calls across threads) while serializing mutations (place, erase).

CMake Integration

Link against ELIPS in your CMakeLists.txt using the target elips::elips:

cmake

cmake_minimum_required(VERSION 3.22)
project(my_vector_app CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(elips REQUIRED)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE elips::elips)

Quick Example

cpp

#include <elips/elips.hpp>
#include <iostream>

int main() {
    // 1. Configure a 128-dimensional Cosine HNSW database
    elips::Config config;
    config.dimension = 128;
    config.metric = elips::Metric::cosine;
    config.index_type = elips::IndexType::hnsw;

    // 2. Open an in-memory database instance
    auto db = elips::open(":memory:", config);
    auto& vault = db->vault("embeddings");

    // 3. Place a vector with metadata payload
    elips::Vector vec(128, 0.5f);
    elips::Payload meta;
    meta["category"] = std::string("finance");
    meta["year"] = int64_t(2026);

    elips::RecordID id = vault.place(vec, meta);
    std::cout << "Inserted record ID: " << id << std::endl;

    // 4. Perform top-K similarity search
    auto results = vault.seek(vec, 5);
    for (const auto& hit : results) {
        std::cout << "Hit ID: " << hit.id << " Score: " << hit.score << std::endl;
    }

    return 0;
}