elips::ElipsInstance is the primary database class in the ELIPS engine. It manages persistent file descriptors, write-ahead logs (WAL), advisory file locking, and vault collection life-cycles.

Overview

An ElipsInstance represents one open database instance bound to a directory path (or ":memory:"). It acts as the container and coordinator for all named Vault partitions within the database.

open() & Constructor

cpp

namespace elips {
    std::unique_ptr<ElipsInstance> open(
        const std::string& path,
        const Config& config = Config{}
    );
}

The factory function elips::open() is the recommended way to open or create an ELIPS database instance.

path — File system directory path for disk-backed persistence, or ":memory:" for volatile in-memory operation.
config — Default Config applied to newly spawned vaults.

Direct Constructor

cpp

ElipsInstance(
    std::string path,
    Config config,
    bool persistent,
    std::optional<LockManager> lock = std::nullopt
);

Vault Management

cpp

Vault& vault(const std::string& name);
std::vector<std::string> list_vaults() const;
Vault& adopt_vault(std::unique_ptr<Vault> vault);

vault(name) — Gets a reference to an existing vault or lazily creates a new vault with the instance's default Config.
list_vaults() — Returns a vector containing the names of all active vaults.
adopt_vault(vault) — Attaches a custom initialized Vault to the instance registry.

Transactions

cpp

Transaction begin_transaction();

Starts an atomic multi-vault write transaction. Returns a Transaction object.

query() (EQL)

cpp

std::vector<SearchResult> query(
    const std::string& eql,
    const std::map<std::string, Vector>& bindings = {}
);

Executes a declarative ELIPS Query Language (EQL) string against the database instance with vector binding parameters.

Maintenance & Checkpoints

cpp

void checkpoint();
void compact();
void vacuum();
void close();
void abandon() noexcept;

checkpoint() — Flushes memory-mapped pages and truncates the WAL log up to the latest sequence number.
compact() — Rewrites storage segment files on disk to eliminate unreferenced tombstones and shrink file sizes.
vacuum() — Reclaims deleted vector nodes within HNSW graph indices across all open vaults.
close() — Safely seals all vaults, flushes WAL, and releases process lock handlers.

Introspection & GPU

cpp

WAL* wal() const noexcept;
const Config& config() const noexcept;
const std::string& path() const noexcept;
bool persistent() const noexcept;
bool closed() const noexcept;

#ifdef ELIPS_GPU_ENABLED
gpu::GpuDeviceInfo gpu_info() const;
gpu::GpuMetricsSnapshot gpu_stats() const;
#endif

Thread Safety & Concurrency

ElipsInstance is completely thread-safe. Concurrent calls to vault(), list_vaults(), and checkpoint() across threads are serialized via internal recursive locks.