refactor(algorithm): extract common search helpers to InnerIndexInterface base class (#2139)

refactor(index): extract common search helpers into InnerIndexInterface

Extract repetitive validation, filter composition, result packing, and
serialization logic into protected helper methods, eliminating ~254 lines
of duplicated boilerplate across 6 index implementations.

New helpers in InnerIndexInterface:
- validate_knn_args / validate_range_args / validate_search_query
- create_search_filter (supports InnerIdWrapperFilter & ExtraInfoWrapperFilter)
- pack_knn_result / pack_knn_result_with_extra_info / make_empty_result
- write_index_footer / read_index_footer

Applied to: BruteForce, HGraph, IVF, Pyramid, SINDI, and WARP.

Assisted-by: OpenCode:claude-opus-4.7
Signed-off-by: LHT129 <tianlan.lht@antgroup.com>

Author: LHT129

src/algorithm/bruteforce/bruteforce.cpp

@@ -210,16 +210,7 @@ BruteForce::SearchWithRequest(const SearchRequest& request) const {
     ExecutorPtr executor = nullptr;
     Filter* attr_filter = nullptr;
 
-    auto combined_filter = std::make_shared<CombinedFilter>();
-    combined_filter->AppendFilter(this->label_table_->GetDeletedIdsFilter());
-    if (request.filter_ != nullptr) {
-        combined_filter->AppendFilter(
-            std::make_shared<InnerIdWrapperFilter>(request.filter_, *this->label_table_));
-    }
-    FilterPtr ft = nullptr;
-    if (not combined_filter->IsEmpty()) {
-        ft = combined_filter;
-    }
+    FilterPtr ft = this->create_search_filter(request.filter_);
 
     if (request.enable_attribute_filter_) {
         auto& schema = this->attr_filter_index_->field_type_map_;
@@ -277,19 +268,13 @@ BruteForce::SearchWithRequest(const SearchRequest& request) const {
         }
     }
 
-    auto [dataset_results, dists, ids] =
-        create_fast_dataset(static_cast<int64_t>(heap->Size()), allocator_);
-    for (auto j = static_cast<int64_t>(heap->Size() - 1); j >= 0; --j) {
-        dists[j] = heap->Top().first;
-        ids[j] = this->label_table_->GetLabelById(heap->Top().second);
-        heap->Pop();
-    }
+    auto result = this->pack_knn_result(heap);
 
     JsonType stats;
     stats["dist_cmp"].SetInt(dist_cmp.load(std::memory_order_relaxed));
-    dataset_results->Statistics(stats.Dump());
+    result->Statistics(stats.Dump());
 
-    return std::move(dataset_results);
+    return result;
 }
 
 DatasetPtr
@@ -300,14 +285,12 @@ BruteForce::RangeSearch(const vsag::DatasetPtr& query,
                         int64_t limited_size) const {
     std::shared_lock read_lock(this->global_mutex_);
     auto computer = this->inner_codes_->FactoryComputer(query->GetFloat32Vectors());
-    CHECK_ARGUMENT(limited_size != 0,
-                   fmt::format("limited_size({}) must not be equal to 0", limited_size));
+    this->validate_range_args(query, radius, limited_size);
     if (limited_size < 0) {
         limited_size = std::numeric_limits<int64_t>::max();
     }
     if (total_count_ == 0) {
-        auto [dataset_results, dists, ids] = create_fast_dataset(0, allocator_);
-        return std::move(dataset_results);
+        return make_empty_result();
     }
 
     auto brute_force_params = BruteForceSearchParameters::FromJson(parameters);
@@ -352,14 +335,7 @@ BruteForce::RangeSearch(const vsag::DatasetPtr& query,
         }
     }
 
-    auto [dataset_results, dists, ids] =
-        create_fast_dataset(static_cast<int64_t>(heap->Size()), allocator_);
-    for (auto j = static_cast<int64_t>(heap->Size() - 1); j >= 0; --j) {
-        dists[j] = heap->Top().first;
-        ids[j] = this->label_table_->GetLabelById(heap->Top().second);
-        heap->Pop();
-    }
-    return std::move(dataset_results);
+    return this->pack_knn_result(heap);
 }
 
 float
@@ -390,34 +366,30 @@ BruteForce::Serialize(StreamWriter& writer) const {
     this->label_table_->Serialize(writer);
 
     // serialize footer (introduced since v0.15)
-    auto metadata = std::make_shared<Metadata>();
     JsonType basic_info;
     basic_info["dim"].SetInt(dim_);
     basic_info["total_count"].SetInt(total_count_);
     basic_info[INDEX_PARAM].SetString(this->create_param_ptr_->ToString());
-    metadata->Set("basic_info", basic_info);
-    auto footer = std::make_shared<Footer>(metadata);
-    footer->Write(writer);
+    write_index_footer(writer, basic_info);
 }
 
 void
 BruteForce::Deserialize(StreamReader& reader) {
     // try to deserialize footer (only in new version)
-    auto footer = Footer::Parse(reader);
+    JsonType basic_info;
+    bool has_footer = read_index_footer(reader, basic_info);
 
     BufferStreamReader buffer_reader(
         &reader, std::numeric_limits<uint64_t>::max(), this->allocator_);
 
-    if (footer == nullptr) {  // old format, DON'T EDIT, remove in the future
+    if (not has_footer) {  // old format, DON'T EDIT, remove in the future
         logger::debug("parse with v0.13 version format");
 
         StreamReader::ReadObj(buffer_reader, dim_);
         StreamReader::ReadObj(buffer_reader, total_count_);
     } else {  // create like `else if ( ver in [v0.15, v0.17] )` here if need in the future
         logger::debug("parse with new version format");
 
-        auto metadata = footer->GetMetadata();
-        auto basic_info = metadata->Get("basic_info");
         if (basic_info.Contains(INDEX_PARAM)) {
             std::string index_param_string = basic_info[INDEX_PARAM].GetString();
             auto index_param = std::make_shared<BruteForceParameter>();

src/algorithm/hgraph/hgraph_search.cpp

@@ -73,12 +73,7 @@ HGraph::KnnSearch(const DatasetPtr& query,
     if (GetNumElements() == 0) {
         return DatasetImpl::MakeEmptyDataset();
     }
-    int64_t query_dim = query->GetDim();
-    if (data_type_ != DataTypes::DATA_TYPE_SPARSE) {
-        CHECK_ARGUMENT(
-            query_dim == dim_,
-            fmt::format("query.dim({}) must be equal to index.dim({})", query_dim, dim_));
-    }
+    this->validate_knn_args(query, k);
 
     auto params = HGraphSearchParameters::FromJson(parameters);
     auto ef_search_threshold = std::max<int64_t>(AMPLIFICATION_FACTOR * k, 1000);
@@ -91,28 +86,9 @@ HGraph::KnnSearch(const DatasetPtr& query,
         force_remove_rlock = std::shared_lock<std::shared_mutex>(this->force_remove_mutex_);
     }
     std::shared_lock shared_lock(this->global_mutex_);
-    // check k
-    CHECK_ARGUMENT(k > 0, fmt::format("k({}) must be greater than 0", k));
     k = std::min(k, GetNumElements());
 
-    // check query vector
-    CHECK_ARGUMENT(query->GetNumElements() == 1, "query dataset should contain 1 vector only");
-
-    auto combined_filter = std::make_shared<CombinedFilter>();
-    combined_filter->AppendFilter(this->label_table_->GetDeletedIdsFilter());
-    if (filter != nullptr) {
-        if (params.use_extra_info_filter) {
-            combined_filter->AppendFilter(
-                std::make_shared<ExtraInfoWrapperFilter>(filter, this->extra_infos_));
-        } else {
-            combined_filter->AppendFilter(
-                std::make_shared<InnerIdWrapperFilter>(filter, *this->label_table_));
-        }
-    }
-    FilterPtr ft = nullptr;
-    if (not combined_filter->IsEmpty()) {
-        ft = combined_filter;
-    }
+    FilterPtr ft = this->create_search_filter(filter, params.use_extra_info_filter);
 
     if (iter_ctx == nullptr) {
         auto cur_count = this->total_count_.load();
@@ -376,32 +352,9 @@ HGraph::RangeSearch(const DatasetPtr& query,
     SearchStatistics stats;
     QueryContext ctx{.stats = &stats};
 
-    auto combined_filter = std::make_shared<CombinedFilter>();
-    combined_filter->AppendFilter(this->label_table_->GetDeletedIdsFilter());
-    if (filter != nullptr) {
-        combined_filter->AppendFilter(
-            std::make_shared<InnerIdWrapperFilter>(filter, *this->label_table_));
-    }
-    FilterPtr ft = nullptr;
-    if (not combined_filter->IsEmpty()) {
-        ft = combined_filter;
-    }
-
-    int64_t query_dim = query->GetDim();
-    if (data_type_ != DataTypes::DATA_TYPE_SPARSE) {
-        CHECK_ARGUMENT(
-            query_dim == dim_,
-            fmt::format("query.dim({}) must be equal to index.dim({})", query_dim, dim_));
-    }
-    // check radius
-    CHECK_ARGUMENT(radius >= 0, fmt::format("radius({}) must be greater equal than 0", radius))
-
-    // check query vector
-    CHECK_ARGUMENT(query->GetNumElements() == 1, "query dataset should contain 1 vector only");
+    FilterPtr ft = this->create_search_filter(filter);
 
-    // check limited_size
-    CHECK_ARGUMENT(limited_size != 0,
-                   fmt::format("limited_size({}) must not be equal to 0", limited_size));
+    this->validate_range_args(query, radius, limited_size);
 
     std::shared_lock<std::shared_mutex> force_remove_rlock;
     if (this->support_force_remove()) {
@@ -477,26 +430,9 @@ HGraph::RangeSearch(const DatasetPtr& query,
         }
     }
 
-    auto count = static_cast<const int64_t>(search_result->Size());
-    auto [dataset_results, dists, ids] = create_fast_dataset(count, allocator_);
-    char* extra_infos = nullptr;
-    if (extra_info_size_ > 0) {
-        extra_infos =
-            static_cast<char*>(allocator_->Allocate(extra_info_size_ * search_result->Size()));
-        dataset_results->ExtraInfos(extra_infos);
-    }
-    for (int64_t j = count - 1; j >= 0; --j) {
-        dists[j] = search_result->Top().first;
-        ids[j] = this->label_table_->GetLabelById(search_result->Top().second);
-        if (extra_infos != nullptr) {
-            this->extra_infos_->GetExtraInfoById(search_result->Top().second,
-                                                 extra_infos + extra_info_size_ * j);
-        }
-        search_result->Pop();
-    }
-
-    dataset_results->Statistics(stats.Dump());
-    return std::move(dataset_results);
+    auto result = this->pack_knn_result_with_extra_info(search_result, allocator_);
+    result->Statistics(stats.Dump());
+    return result;
 }
 
 [[nodiscard]] DatasetPtr
@@ -508,13 +444,8 @@ HGraph::SearchWithRequest(const SearchRequest& request) const {
     }
 
     const auto& query = request.query_;
-    int64_t query_dim = query->GetDim();
     auto k = request.topk_;
-    if (data_type_ != DataTypes::DATA_TYPE_SPARSE) {
-        CHECK_ARGUMENT(
-            query_dim == dim_,
-            fmt::format("query.dim({}) must be equal to index.dim({})", query_dim, dim_));
-    }
+    this->validate_knn_args(query, k);
 
     auto params = HGraphSearchParameters::FromJson(request.params_str_);
 
@@ -528,14 +459,8 @@ HGraph::SearchWithRequest(const SearchRequest& request) const {
         force_remove_rlock = std::shared_lock<std::shared_mutex>(this->force_remove_mutex_);
     }
     std::shared_lock shared_lock(this->global_mutex_);
-
-    // check k
-    CHECK_ARGUMENT(k > 0, fmt::format("k({}) must be greater than 0", k));
     k = std::min(k, GetNumElements());
 
-    // check query vector
-    CHECK_ARGUMENT(query->GetNumElements() == 1, "query dataset should contain 1 vector only");
-
     // Setup reasoning context if expected labels are provided.
     std::shared_ptr<ReasoningContext> reasoning_ctx;
     if (not request.expected_labels_.empty()) {
@@ -591,21 +516,7 @@ HGraph::SearchWithRequest(const SearchRequest& request) const {
         search_param.ep = result->Top().second;
     }
 
-    auto combined_filter = std::make_shared<CombinedFilter>();
-    combined_filter->AppendFilter(this->label_table_->GetDeletedIdsFilter());
-    if (request.filter_ != nullptr) {
-        if (params.use_extra_info_filter) {
-            combined_filter->AppendFilter(
-                std::make_shared<ExtraInfoWrapperFilter>(request.filter_, this->extra_infos_));
-        } else {
-            combined_filter->AppendFilter(
-                std::make_shared<InnerIdWrapperFilter>(request.filter_, *this->label_table_));
-        }
-    }
-    FilterPtr ft = nullptr;
-    if (not combined_filter->IsEmpty()) {
-        ft = combined_filter;
-    }
+    FilterPtr ft = this->create_search_filter(request.filter_, params.use_extra_info_filter);
 
     if (request.enable_attribute_filter_ and this->attr_filter_index_ != nullptr) {
         auto& schema = this->attr_filter_index_->field_type_map_;