Index

vsag::Index（声明于 vsag/index.h）是本库的核心抽象。每一种具体索引 —— HGraph、IVF、DiskANN、 BruteForce、SINDI、Pyramid 等 —— 都实现这一接口。你从不直接实例化 Index，而是通过 Factory::CreateIndex 或 Engine::CreateIndex 获取，并用 IndexPtr （std::shared_ptr<Index>）持有它。

using IndexPtr = std::shared_ptr<Index>;

如何阅读本参考

Index 暴露了许多可选能力。基类为几乎每个方法都提供了默认实现：

• 当具体索引未实现某方法时，大多数方法返回 tl::unexpected(Error(ErrorType::UNSUPPORTED_INDEX_OPERATION, ...))。
• 少数统计访问器则会抛出 std::runtime_error（下文会明确标注）。若在可能不支持它们的索引上调用， 请用 try/catch 包裹。

由于“不支持”是正常且预期的结果，请用 CheckFeature 提前探测能力，而不要假设某个方法一定 可用。标注为 （纯虚函数） 的方法必须由每种索引实现，调用它们总是安全的。

本页通篇用到的指针/句柄类型：DatasetPtr（Dataset）、FilterPtr （Filter）、BitsetPtr（Bitset）、BinarySet / ReaderSet（序列化类型）。

枚举与辅助类型

IndexType

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

由 GetIndexType 返回。

RemoveMode

enum class RemoveMode {
    MARK_REMOVE = 0,   // 标记删除；不收缩/不修复 —— 快
    FORCE_REMOVE = 1,  // 物理删除并修复图 —— 重
};

传入 Remove。

MergeUnit 与 IdMapFunction

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

struct MergeUnit {
    IndexPtr index = nullptr;         // 要合并进来的源子索引
    IdMapFunction id_map_func = nullptr;  // 逐 id 的过滤 + 重映射
};

对每个源 id，id_map_func 返回 {keep, new_id}：keep == true 表示将该向量以目标 id new_id 纳入。 由 Merge 使用。

Checkpoint

struct Index::Checkpoint {
    BinarySet data;       // 中间状态
    bool finish = false;  // 构建完成后为 true
};

由 ContinueBuild 返回，用于驱动增量构建。

数据选择标志

用于 GetDataByIdsWithFlag 的位标志，可通过按位或组合：

WriteFuncType

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

用于流式 Serialize 的落盘回调。每次调用要求你把 SizeType 字节（位于给定源指针处）持久化 到输出中逻辑偏移 OffsetType 的位置。

构建与训练

见 索引构建与训练 与 examples/cpp/311_feature_train.cpp。

更新与删除

见 examples/cpp/303_feature_remove.cpp。

搜索

推荐的入口是 SearchWithRequest，它接收单个 SearchRequest，其中携带查询、模式、top-k / 半径以及各类过滤器。较旧的 逐参数 KnnSearch / RangeSearch 重载为兼容性保留。

每次搜索都返回一个 DatasetPtr：对 KNN，num_elements == 1，ids / distances 长度为 k；对范围 搜索，结果长度即命中数。如何读取结果见 Dataset。

SearchWithRequest

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

由 SearchRequest 驱动的统一 KNN 或范围搜索。这是新代码首选的 API；它通过 一个结构体即可支持属性过滤、回调过滤、bitset 过滤、逐次搜索 allocator 以及迭代式搜索。

KnnSearch 重载

// (1) bitset 预过滤 —— 纯虚函数
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          BitsetPtr invalid = nullptr) const;

// (2) 回调预过滤 —— 纯虚函数
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 对象
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, const std::string& parameters,
          const FilterPtr& filter) const;

// (4) Filter + 迭代上下文
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]]，请改用 SearchWithRequest
tl::expected<DatasetPtr, Error>
KnnSearch(const DatasetPtr& query, int64_t k, SearchParam& search_param) const;

关于 filter 参数的说明：

• 在重载 (1)/(2) 中，谓词/bitset 标记的是被过滤掉的向量。对 bitset，Test(id) == true 表示该 id 被排除；对 std::function 谓词，返回 true 表示该 id 被排除。
• 重载 (3)/(4) 接收 Filter 对象，其 CheckValid(id) 采用相反约定 （true 表示保留）。完整语义见 带过滤的搜索 与 examples/cpp/301_feature_filter.cpp。
• 重载 (4) 支撑迭代式搜索；跨调用传入同一个 iter_ctx，并在最后一次 调用时设置 is_last_search。

RangeSearch 重载

// (1) 普通 —— 纯虚函数
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            int64_t limited_size = -1) const;

// (2) bitset 预过滤 —— 纯虚函数
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            BitsetPtr invalid, int64_t limited_size = -1) const;

// (3) 回调预过滤 —— 纯虚函数
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 对象
tl::expected<DatasetPtr, Error>
RangeSearch(const DatasetPtr& query, float radius, const std::string& parameters,
            const FilterPtr& filter, int64_t limited_size = -1) const;

radius 限定距离上界；limited_size 限制结果数量（<= 0 表示不限，0 为错误）。见 范围搜索 与 examples/cpp/302_feature_range_search.cpp。

按 id 计算距离

calculate_precise_distance = true 时可能会加载全精度向量（可能来自磁盘）而非量化编码。见 按 ID 计算距离 与 examples/cpp/306_feature_calculate_distance_by_id.cpp。

共轭图增强

见 图索引增强。

数据获取

见 索引自省 与 examples/cpp/317_feature_get_detail_data.cpp。

能力探测、合并、克隆与导出

见 examples/cpp/309_feature_clone.cpp、310_feature_export_model.cpp、 315_feature_hgraph_merge.cpp，以及 索引生命周期管理。

序列化

在非空索引上反序列化会得到 INDEX_NOT_EMPTY。见 序列化格式 与 examples/cpp/401_persistent_kv.cpp / 402_persistent_streaming.cpp。

缓存（构建加速）

统计与自省

除非另有说明，这些方法直接返回值。标注为“抛出”的方法在索引不支持时会抛出 std::runtime_error （而非 tl::expected）。

见 examples/cpp/308_feature_estimate_memory.cpp、319_feature_get_memory_usage.cpp，以及 索引分析工具。

参见

• Dataset —— 构造查询/基础输入并读取搜索结果。
• 搜索请求与过滤器 —— SearchRequest 字段与过滤器类型。
• 序列化类型 —— BinarySet、Binary、Reader、ReaderSet。
• 辅助类型 —— IndexFeature、IndexDetailInfo、AttributeSet。