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 Database, Collection, 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::Database — Top-level database handle managing storage, WAL, locking, and multi-collection registries.
elips::Collection — 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<Database>.
When Database is destroyed, it flushes pending WAL logs, executes a database checkpoint (for persistent databases), and releases file lock handles.
Collection objects are owned by their parent Database 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: Database uses a recursive mutex for collection registry lookups. Each Collection contains a std::shared_mutex allowing arbitrary concurrent readers (e.g. search calls across threads) while serializing mutations (add, remove).

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& collection = db->collection("embeddings");

    // 3. Add 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 = collection.add(vec, meta);
    std::cout << "Inserted record ID: " << id << std::endl;

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

    return 0;
}