Index

vsag::Index (declared in vsag/index.h) is the central abstraction of the library. Every concrete index type — HGraph, IVF, DiskANN, BruteForce, SINDI, Pyramid, and so on — implements this interface. You never instantiate Index directly; obtain one from Factory::CreateIndex or Engine::CreateIndex and hold it through IndexPtr (std::shared_ptr<Index>).

using IndexPtr = std::shared_ptr<Index>;

How to read this reference

Index exposes many optional capabilities. The base class provides a default implementation for almost every method:

• Most methods return tl::unexpected(Error(ErrorType::UNSUPPORTED_INDEX_OPERATION, ...)) when the concrete index does not implement them.
• A handful of statistics accessors instead throw std::runtime_error (called out explicitly below). Wrap those in try/catch if you call them on an index that may not support them.

Because “unsupported” is a normal, expected outcome, probe capabilities up front with CheckFeature rather than assuming a method works. Methods marked (pure virtual) must be implemented by every index and are always safe to call.

Pointer/handle types used throughout this page: DatasetPtr (Dataset), FilterPtr (Filter), BitsetPtr (Bitset), BinarySet / ReaderSet (Serialization Types).

Enumerations and helper types

IndexType

enum class IndexType {
    HNSW, DISKANN, HGRAPH, IVF, PYRAMID, BRUTEFORCE, SPARSE, SINDI, WARP, LAZY_HGRAPH, SIMQ
};

Returned by GetIndexType.

RemoveMode

enum class RemoveMode {
    MARK_REMOVE = 0,   // mark as deleted; no shrink/repair — fast
    FORCE_REMOVE = 1,  // physically remove and repair the graph — heavy
};

Passed to Remove.

MergeUnit and IdMapFunction

using IdMapFunction = std::function<std::tuple<bool, int64_t>(int64_t)>;

struct MergeUnit {
    IndexPtr index = nullptr;         // source sub-index to merge from
    IdMapFunction id_map_func = nullptr;  // per-id filter + remap
};

For each source id, id_map_func returns {keep, new_id}: keep == true includes the vector under target id new_id. Used by Merge.

Checkpoint

struct Index::Checkpoint {
    BinarySet data;       // intermediate state
    bool finish = false;  // true once the build is complete
};

Returned by ContinueBuild to drive incremental builds.

Data-selection flags

Bit flags for GetDataByIdsWithFlag, combined with bitwise OR:

WriteFuncType

using OffsetType = uint64_t;
using SizeType = uint64_t;
using WriteFuncType = std::function<void(OffsetType, SizeType, const void*)>;

A sink callback for streaming Serialize. Each call asks you to persist SizeType bytes (at the given source pointer) at logical OffsetType in the output.

Build & train

See Build and Train and examples/cpp/311_feature_train.cpp.

Update & remove

See examples/cpp/303_feature_remove.cpp.

Search

The recommended entry point is SearchWithRequest, which takes a single SearchRequest carrying the query, mode, top-k / radius, and any filters. The older per-argument KnnSearch / RangeSearch overloads remain for compatibility.

Every search returns a DatasetPtr: for KNN, num_elements == 1 and ids / distances have length k; for range search, the result length is the number of matches. See Dataset for how to read results.

SearchWithRequest

[[nodiscard]] tl::expected<DatasetPtr, Error>
SearchWithRequest(const SearchRequest& request) const;

Unified KNN or range search driven by SearchRequest. This is the preferred API for new code; it supports attribute filters, callback filters, bitset filters, a per-search allocator, and iterator search through one struct.

KnnSearch overloads

// (1) bitset pre-filter — pure virtual
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          BitsetPtr invalid = nullptr) const;

// (2) callback pre-filter — pure virtual
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          const std::function<bool(int64_t)>& filter) const;

// (3) Filter object
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          const FilterPtr& filter) const;

// (4) Filter + iterator context
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          const FilterPtr& filter, IteratorContext*& iter_ctx, bool is_last_search) const;

// (5) SearchParam — [[deprecated]], use SearchWithRequest
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, SearchParam& search_param) const;

Notes on the filter argument:

• In overloads (1)/(2) the predicate/bitset marks vectors filtered out. For a bitset, Test(id) == true means id is excluded. For the std::function predicate, returning true means the id is excluded.
• Overload (3)/(4) take a Filter object, whose CheckValid(id) uses the opposite convention (true means keep). See Filtered Search for the full semantics, and examples/cpp/301_feature_filter.cpp.
• Overload (4) powers Iterator Search; pass the same iter_ctx across calls and set is_last_search on the final call.

RangeSearch overloads

// (1) plain — pure virtual
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            int64_t limited_size = -1) const;

// (2) bitset pre-filter — pure virtual
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            BitsetPtr invalid, int64_t limited_size = -1) const;

// (3) callback pre-filter — pure virtual
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            const std::function<bool(int64_t)>& filter, int64_t limited_size = -1) const;

// (4) Filter object
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            const FilterPtr& filter, int64_t limited_size = -1) const;

radius bounds the distance; limited_size caps the result count (<= 0 means no limit, 0 is an error). See Range Search and examples/cpp/302_feature_range_search.cpp.

Distance by id

calculate_precise_distance = true may load full-precision vectors (possibly from disk) instead of quantized codes. See Calculate Distance by ID and examples/cpp/306_feature_calculate_distance_by_id.cpp.

Conjugate-graph enhancement

See Graph Enhancement.

Data retrieval

See Index Introspection and examples/cpp/317_feature_get_detail_data.cpp.

Capabilities, merge, clone, export

See examples/cpp/309_feature_clone.cpp, 310_feature_export_model.cpp, and 315_feature_hgraph_merge.cpp, plus Index Lifecycle Management.

Serialization

Deserializing onto a non-empty index yields INDEX_NOT_EMPTY. See Serialization and examples/cpp/401_persistent_kv.cpp / 402_persistent_streaming.cpp.

Cache (build acceleration)

Statistics & introspection

Unless noted, these return values directly. The methods marked “throws” raise std::runtime_error (not tl::expected) when the index does not support them.

See examples/cpp/308_feature_estimate_memory.cpp, 319_feature_get_memory_usage.cpp, and the Index Analysis Tool.

See also

• Dataset — construct query/base inputs and read search results.
• Search Request & Filters — the SearchRequest fields and filter types.
• Serialization Types — BinarySet, Binary, Reader, ReaderSet.
• Auxiliary Types — IndexFeature, IndexDetailInfo, AttributeSet.