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

Overview

Collections are named partitions created via db->collection("name"). They expose methods for vector ingestion, text embedding, multi-modal search, boolean metadata filtering, and graph compaction.

Add & Ingestion

cpp

RecordID add(
    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 add_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 add_many(const std::vector<Record>& records);

add() — Inserts a raw floating-point vector into the collection index and returns its RecordID.
add_document() — Invokes the configured text embedder engine to convert raw text into a vector before indexing.
add_many() — Efficient batch add of pre-constructed records.

Searching & Querying

cpp

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

std::vector<SearchResult> search_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 distance.

Hybrid Search

cpp

std::vector<SearchResult> hybrid_search(
    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_query()

cpp

QueryPlan explain_query(
    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, flat exact scan, or metadata-accelerated filtering will be selected by the optimizer.

Scan & Get

cpp

std::optional<Record> get(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;

Removal & Vacuum

cpp

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

remove() — Tombstones a record ID. (C++ uses remove; the Python binding exposes delete.)
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 Collection is thread-safe. Read operations take a shared reader lock (std::shared_mutex::lock_shared), enabling parallel search operations across CPU threads.