Add filter for cagra::merge

build.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# SPDX-FileCopyrightText: Copyright (c) 2020-2025, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2020-2026, NVIDIA CORPORATION.
 # SPDX-License-Identifier: Apache-2.0
 
 # cuvs build scripts
@@ -54,7 +54,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
    --no-nvtx                   - disable nvtx (profiling markers), but allow enabling it in downstream projects
    --no-shared-libs            - build without shared libraries
    --show_depr_warn            - show cmake deprecation warnings
-   --run-java-test             - run Java tests after building
+   --run-java-tests            - run Java tests after building
    --build-metrics             - filename for generating build metrics report for libcuvs
    --incl-cache-stats          - include cache statistics in build metrics report
    --cmake-args=\\\"<args>\\\" - pass arbitrary list of CMake configuration options (escape all quotes in argument)

c/include/cuvs/neighbors/cagra.h

@@ -559,33 +559,6 @@ cuvsError_t cuvsCagraIndexGetDataset(cuvsCagraIndex_t index, DLManagedTensor* da
  */
 cuvsError_t cuvsCagraIndexGetGraph(cuvsCagraIndex_t index, DLManagedTensor* graph);
 
-/**
- * @}
- */
-
-/**
- * @defgroup cagra_c_merge_params C API for CUDA ANN Graph-based nearest neighbor search
- * @{
- */
-
-/**
- * @brief Supplemental parameters to merge CAGRA index
- *
- */
-
-struct cuvsCagraMergeParams {
-  cuvsCagraIndexParams_t output_index_params;
-  cuvsMergeStrategy strategy;
-};
-
-typedef struct cuvsCagraMergeParams* cuvsCagraMergeParams_t;
-
-/** Allocate CAGRA merge params with default values */
-cuvsError_t cuvsCagraMergeParamsCreate(cuvsCagraMergeParams_t* params);
-
-/** De-allocate CAGRA merge params */
-cuvsError_t cuvsCagraMergeParamsDestroy(cuvsCagraMergeParams_t params);
-
 /**
  * @}
  */
@@ -859,7 +832,7 @@ cuvsError_t cuvsCagraIndexFromArgs(cuvsResources_t res,
  *
  * All input indices must have been built with the same data type (`index.dtype`) and
  * have the same dimensionality (`index.dims`). The merged index uses the output
- * parameters specified in `cuvsCagraMergeParams`.
+ * parameters specified in `cuvsCagraIndexParams`.
  *
  * Input indices must have:
  *  - `index.dtype.code` and `index.dtype.bits` matching across all indices.
@@ -886,29 +859,31 @@ cuvsError_t cuvsCagraIndexFromArgs(cuvsResources_t res,
  *
  * // Assume index1 and index2 have been built using cuvsCagraBuild
  *
- * cuvsCagraMergeParams_t merge_params;
- * cuvsError_t params_create_status = cuvsCagraMergeParamsCreate(&merge_params);
+ * cuvsCagraIndexParams_t merge_params;
+ * cuvsError_t params_create_status = cuvsCagraIndexParamsCreate(&merge_params);
  *
  * cuvsError_t merge_status = cuvsCagraMerge(res, merge_params, (cuvsCagraIndex_t[]){index1,
  * index2}, 2, merged_index);
  *
  * // Use merged_index for search operations
  *
- * cuvsError_t params_destroy_status = cuvsCagraMergeParamsDestroy(merge_params);
+ * cuvsError_t params_destroy_status = cuvsCagraIndexParamsDestroy(merge_params);
  * cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);
  * @endcode
  *
  * @param[in] res cuvsResources_t opaque C handle
- * @param[in] params cuvsCagraMergeParams_t parameters controlling merge behavior
+ * @param[in] params cuvsCagraIndexParams_t parameters controlling merge behavior
  * @param[in] indices Array of input cuvsCagraIndex_t handles to merge
  * @param[in] num_indices Number of input indices
+ * @param[in] filter Filter that can be used to filter out vectors from the merged index
  * @param[out] output_index Output handle that will store the merged index.
  *                          Must be initialized using `cuvsCagraIndexCreate` before use.
  */
 cuvsError_t cuvsCagraMerge(cuvsResources_t res,
-                           cuvsCagraMergeParams_t params,
+                           cuvsCagraIndexParams_t params,
                            cuvsCagraIndex_t* indices,
                            size_t num_indices,
+                           cuvsFilter filter,
                            cuvsCagraIndex_t output_index);
 
 /**

c/src/neighbors/cagra.cpp

@@ -293,23 +293,23 @@ void* _deserialize(cuvsResources_t res, const char* filename)
 
 template <typename T>
 void* _merge(cuvsResources_t res,
-             cuvsCagraMergeParams params,
+             cuvsCagraIndexParams params,
              cuvsCagraIndex_t* indices,
-             size_t num_indices)
+             size_t num_indices,
+             cuvsFilter filter)
 {
   auto res_ptr = reinterpret_cast<raft::resources*>(res);
-  cuvs::neighbors::cagra::merge_params merge_params_cpp;
-  auto& out_idx_params = *params.output_index_params;
+  cuvs::neighbors::cagra::index_params params_cpp;
 
-  merge_params_cpp.output_index_params.metric =
-    static_cast<cuvs::distance::DistanceType>((int)out_idx_params.metric);
-  merge_params_cpp.output_index_params.intermediate_graph_degree =
-    out_idx_params.intermediate_graph_degree;
-  merge_params_cpp.output_index_params.graph_degree = out_idx_params.graph_degree;
+  params_cpp.metric =
+    static_cast<cuvs::distance::DistanceType>((int)params.metric);
+  params_cpp.intermediate_graph_degree =
+    params.intermediate_graph_degree;
+  params_cpp.graph_degree = params.graph_degree;
 
   int64_t total_size = 0;
   int64_t dim        = 0;
-  if (out_idx_params.build_algo == cuvsCagraGraphBuildAlgo::IVF_PQ) {
+  if (params.build_algo == cuvsCagraGraphBuildAlgo::IVF_PQ) {
     auto first_idx_ptr =
       reinterpret_cast<cuvs::neighbors::cagra::index<T, uint32_t>*>(indices[0]->addr);
     dim = first_idx_ptr->dim();
@@ -320,9 +320,9 @@ void* _merge(cuvsResources_t res,
     }
   }
 
-  _set_graph_build_params(merge_params_cpp.output_index_params.graph_build_params,
-                          out_idx_params,
-                          out_idx_params.build_algo,
+  _set_graph_build_params(params_cpp.graph_build_params,
+                          params,
+                          params.build_algo,
                           total_size,
                           dim);
 
@@ -333,10 +333,21 @@ void* _merge(cuvsResources_t res,
     index_ptrs.push_back(idx_ptr);
   }
 
-  auto merged_index = new cuvs::neighbors::cagra::index<T, uint32_t>(
-    cuvs::neighbors::cagra::merge(*res_ptr, merge_params_cpp, index_ptrs));
-
-  return merged_index;
+  if (filter.type == NO_FILTER) {
+    return new cuvs::neighbors::cagra::index<T, uint32_t>(
+      cuvs::neighbors::cagra::merge(*res_ptr, params_cpp, index_ptrs));
+  } else if (filter.type == BITSET) {
+    using filter_mdspan_type    = raft::device_vector_view<std::uint32_t, int64_t, raft::row_major>;
+    auto removed_indices_tensor = reinterpret_cast<DLManagedTensor*>(filter.addr);
+    auto removed_indices = cuvs::core::from_dlpack<filter_mdspan_type>(removed_indices_tensor);
+    cuvs::core::bitset_view<std::uint32_t, int64_t> removed_indices_bitset(
+      removed_indices, total_size);
+    auto bitset_filter_obj = cuvs::neighbors::filtering::bitset_filter(removed_indices_bitset);
+    return new cuvs::neighbors::cagra::index<T, uint32_t>(
+      cuvs::neighbors::cagra::merge(*res_ptr, params_cpp, index_ptrs, bitset_filter_obj));
+  } else {
+    RAFT_FAIL("Unsupported filter type: BITMAP");
+  }
 }
 
 template <typename T, typename IdxT>
@@ -678,14 +689,17 @@ extern "C" cuvsError_t cuvsCagraSearch(cuvsResources_t res,
 }
 
 extern "C" cuvsError_t cuvsCagraMerge(cuvsResources_t res,
-                                      cuvsCagraMergeParams_t params,
+                                      cuvsCagraIndexParams_t params,
                                       cuvsCagraIndex_t* indices,
                                       size_t num_indices,
+                                      cuvsFilter filter,
                                       cuvsCagraIndex_t output_index)
 {
   return cuvs::core::translate_exceptions([=] {
     // Basic checks on inputs
     RAFT_EXPECTS(indices != nullptr && num_indices > 0, "indices array cannot be null or empty");
+    RAFT_EXPECTS(params != nullptr, "params cannot be null");
+
     // Use first index dtype as reference
     auto dtype = (*indices[0]).dtype;
     for (size_t i = 1; i < num_indices; ++i) {
@@ -698,16 +712,16 @@ extern "C" cuvsError_t cuvsCagraMerge(cuvsResources_t res,
     // Dispatch based on data type
     if (dtype.code == kDLFloat && dtype.bits == 32) {
       output_index->addr =
-        reinterpret_cast<uintptr_t>(_merge<float>(res, *params, indices, num_indices));
+        reinterpret_cast<uintptr_t>(_merge<float>(res, *params, indices, num_indices, filter));
     } else if (dtype.code == kDLFloat && dtype.bits == 16) {
       output_index->addr =
-        reinterpret_cast<uintptr_t>(_merge<half>(res, *params, indices, num_indices));
+        reinterpret_cast<uintptr_t>(_merge<half>(res, *params, indices, num_indices, filter));
     } else if (dtype.code == kDLInt && dtype.bits == 8) {
       output_index->addr =
-        reinterpret_cast<uintptr_t>(_merge<int8_t>(res, *params, indices, num_indices));
+        reinterpret_cast<uintptr_t>(_merge<int8_t>(res, *params, indices, num_indices, filter));
     } else if (dtype.code == kDLUInt && dtype.bits == 8) {
       output_index->addr =
-        reinterpret_cast<uintptr_t>(_merge<uint8_t>(res, *params, indices, num_indices));
+        reinterpret_cast<uintptr_t>(_merge<uint8_t>(res, *params, indices, num_indices, filter));
     } else {
       RAFT_FAIL("Unsupported index data type: code=%d, bits=%d", dtype.code, dtype.bits);
     }
@@ -850,24 +864,6 @@ extern "C" cuvsError_t cuvsCagraSearchParamsDestroy(cuvsCagraSearchParams_t para
   return cuvs::core::translate_exceptions([=] { delete params; });
 }
 
-extern "C" cuvsError_t cuvsCagraMergeParamsCreate(cuvsCagraMergeParams_t* params)
-{
-  return cuvs::core::translate_exceptions([=] {
-    cuvsCagraIndexParams_t idx_params;
-    cuvsCagraIndexParamsCreate(&idx_params);
-    *params = new cuvsCagraMergeParams{.output_index_params = idx_params,
-                                       .strategy            = MERGE_STRATEGY_PHYSICAL};
-  });
-}
-
-extern "C" cuvsError_t cuvsCagraMergeParamsDestroy(cuvsCagraMergeParams_t params)
-{
-  return cuvs::core::translate_exceptions([=] {
-    cuvsCagraIndexParamsDestroy(params->output_index_params);
-    delete params;
-  });
-}
-
 extern "C" cuvsError_t cuvsCagraDeserialize(cuvsResources_t res,
                                             const char* filename,
                                             cuvsCagraIndex_t index)

c/tests/neighbors/ann_cagra_c.cu

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -503,13 +503,15 @@ TEST(CagraC, BuildMergeSearch)
   ASSERT_EQ(cuvsCagraBuild(res, build_params, &main_dataset_tensor, index_main), CUVS_SUCCESS);
   ASSERT_EQ(cuvsCagraBuild(res, build_params, &additional_dataset_tensor, index_add), CUVS_SUCCESS);
 
-  cuvsCagraMergeParams_t merge_params;
-  cuvsCagraMergeParamsCreate(&merge_params);
   cuvsCagraIndex_t index_merged;
   cuvsCagraIndexCreate(&index_merged);
 
+  cuvsFilter filter;
+  filter.type = NO_FILTER;
+  filter.addr = 0;
+
   cuvsCagraIndex_t index_array[2] = {index_main, index_add};
-  ASSERT_EQ(cuvsCagraMerge(res, merge_params, index_array, 2, index_merged), CUVS_SUCCESS);
+  ASSERT_EQ(cuvsCagraMerge(res, build_params, index_array, 2, filter, index_merged), CUVS_SUCCESS);
 
   int64_t merged_dim = -1;
   ASSERT_EQ(cuvsCagraIndexGetDims(index_merged, &merged_dim), CUVS_SUCCESS);
@@ -541,9 +543,6 @@ TEST(CagraC, BuildMergeSearch)
   cuvsCagraSearchParamsCreate(&search_params);
   (*search_params).itopk_size = 1;
 
-  cuvsFilter filter;
-  filter.type = NO_FILTER;
-  filter.addr = 0;
   ASSERT_EQ(cuvsCagraSearch(res,
                             search_params,
                             index_merged,
@@ -563,7 +562,6 @@ TEST(CagraC, BuildMergeSearch)
   EXPECT_NEAR(distance_host, 0.0f, 1e-6);
 
   cuvsCagraSearchParamsDestroy(search_params);
-  cuvsCagraMergeParamsDestroy(merge_params);
   cuvsCagraIndexParamsDestroy(build_params);
   cuvsCagraIndexDestroy(index_merged);
   cuvsCagraIndexDestroy(index_add);

cpp/bench/ann/src/cuvs/cuvs_cagra_wrapper.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
@@ -221,17 +221,14 @@ void cuvs_cagra<T, IdxT>::build(const T* dataset, size_t nrow)
       sub_indices_.push_back(std::move(sub_index_shared));
     }
     if (index_params_.merge_type == CagraMergeType::kPhysical) {
-      cuvs::neighbors::cagra::merge_params merge_params{params};
-      merge_params.merge_strategy = cuvs::neighbors::MergeStrategy::MERGE_STRATEGY_PHYSICAL;
-
       std::vector<cuvs::neighbors::cagra::index<T, IdxT>*> indices;
       indices.reserve(sub_indices_.size());
       for (auto& ptr : sub_indices_) {
         indices.push_back(ptr.get());
       }
 
       index_ = std::make_shared<cuvs::neighbors::cagra::index<T, IdxT>>(
-        std::move(cuvs::neighbors::cagra::merge(handle_, merge_params, indices)));
+        std::move(cuvs::neighbors::cagra::merge(handle_, params, indices)));
     }
   }
 }