elips::Vault is the core collection container in ELIPS. Each vault owns its HNSW/exact vector index, metadata inverted index, and payload store.

Overview

Vaults are named collections created via db->vault("name"). They expose methods for vector ingestion, text embedding placement, multi-modal seeking, boolean metadata filtering, and graph compaction.

Placement & Ingestion

cpp

RecordID place(
    const Vector& vector,
    Payload payload = {},
    std::optional<RecordID> id = std::nullopt,
    std::optional<DocumentAttachment> document = std::nullopt,
    std::optional<ChunkInfo> chunk = std::nullopt,
    std::optional<EmbeddingLineage> lineage = std::nullopt
);

RecordID place_document(
    std::string text,
    Payload payload = {},
    std::optional<RecordID> id = std::nullopt,
    std::optional<ChunkInfo> chunk = std::nullopt,
    std::optional<EmbeddingLineage> lineage = std::nullopt
);

void place_many(const std::vector<Record>& records);

place() — Inserts a raw floating-point vector into the vault index and returns its RecordID.
place_document() — Invokes the configured text embedder engine to convert raw text into a vector before indexing.
place_many() — Efficient batch placement of pre-constructed records.

Seeking & Querying

cpp

std::vector<SearchResult> seek(
    const Vector& query,
    std::size_t top,
    const Filter& filter = Filter{},
    std::optional<float> threshold = std::nullopt
) const;

std::vector<SearchResult> seek_text(
    std::string_view text,
    std::size_t top,
    const Filter& filter = Filter{},
    std::optional<float> threshold = std::nullopt
) const;

Executes vector similarity search. Returns an ordered list of SearchResult items sorted by score.

Hybrid Search

cpp

std::vector<SearchResult> seek_hybrid(
    const Vector& query,
    std::string_view text,
    std::size_t top,
    const Filter& filter = Filter{},
    std::optional<float> threshold = std::nullopt,
    float lexical_weight = 0.25F
) const;

Fuses dense vector similarity with sparse BM25 text relevance scores using lexical_weight.

explain_seek()

cpp

QueryPlan explain_seek(
    const Vector& query,
    std::size_t top,
    const Filter& filter = Filter{},
    std::optional<float> threshold = std::nullopt,
    bool has_text_component = false
) const;

Returns an inspection QueryPlan object detailing whether HNSW graph traversal, exact scan, or metadata-accelerated filtering will be selected by the optimizer.

Scan & Fetch

cpp

std::optional<Record> fetch(const RecordID& id) const;

std::vector<Record> scan(
    const Filter& filter = Filter{},
    std::size_t offset = 0,
    std::size_t limit = std::numeric_limits<std::size_t>::max()
) const;

Erasure & Vacuum

cpp

bool erase(const RecordID& id);
void vacuum();
std::size_t pending_removals() const noexcept;
void rebuild_index();

erase() — Tombstones a record ID.
vacuum() — Purges tombstoned node slots from HNSW graph indices and reclaims memory.
pending_removals() — Returns the count of un-vacuumed tombstones.

Concurrency & Locking

Every public method on Vault is thread-safe. Read operations take a shared reader lock (std::shared_mutex::lock_shared), enabling parallel seek operations across CPU threads.