@@ -223,6 +223,27 @@ struct cuvsCagraIndexParams {
223223
224224typedef struct cuvsCagraIndexParams * cuvsCagraIndexParams_t ;
225225
226+ /** Algorithm used to merge physical CAGRA indices. */
227+ enum cuvsCagraMergeAlgo {
228+ CUVS_CAGRA_MERGE_AUTO = 0 ,
229+ CUVS_CAGRA_MERGE_FASTENER = 1 ,
230+ CUVS_CAGRA_MERGE_REBUILD = 2
231+ };
232+
233+ /** Parameters controlling how physical CAGRA indices are merged. */
234+ struct cuvsCagraMergeParams {
235+ enum cuvsCagraMergeAlgo algo ;
236+ uint32_t levels ;
237+ uint32_t root_fanout ;
238+ uint32_t lower_fanout ;
239+ double leader_fraction ;
240+ uint32_t max_leaders ;
241+ uint32_t leaf_size ;
242+ uint32_t leaf_degree ;
243+ };
244+
245+ typedef struct cuvsCagraMergeParams * cuvsCagraMergeParams_t ;
246+
226247/**
227248 * @brief Allocate CAGRA Index params, and populate with default values
228249 *
@@ -239,6 +260,12 @@ CUVS_EXPORT cuvsError_t cuvsCagraIndexParamsCreate(cuvsCagraIndexParams_t* param
239260 */
240261CUVS_EXPORT cuvsError_t cuvsCagraIndexParamsDestroy (cuvsCagraIndexParams_t params );
241262
263+ /** Allocate CAGRA merge params and populate them with AUTO defaults. */
264+ CUVS_EXPORT cuvsError_t cuvsCagraMergeParamsCreate (cuvsCagraMergeParams_t * params );
265+
266+ /** De-allocate CAGRA merge params. */
267+ CUVS_EXPORT cuvsError_t cuvsCagraMergeParamsDestroy (cuvsCagraMergeParams_t params );
268+
242269/**
243270 * @brief Allocate CAGRA Compression params, and populate with default values
244271 *
@@ -967,7 +994,7 @@ CUVS_EXPORT cuvsError_t cuvsCagraIndexFromArgs(cuvsResources_t res,
967994 *
968995 * All input indices must have been built with the same data type (`index.dtype`) and
969996 * have the same dimensionality (`index.dims`). The merged index uses the output
970- * parameters specified in `cuvsCagraIndexParams`.
997+ * parameters specified in `cuvsCagraIndexParams`. The merge algorithm is selected automatically.
971998 *
972999 * Input indices must have:
9731000 * - `index.dtype.code` and `index.dtype.bits` matching across all indices.
@@ -1013,7 +1040,7 @@ CUVS_EXPORT cuvsError_t cuvsCagraIndexFromArgs(cuvsResources_t res,
10131040 * @endcode
10141041 *
10151042 * @param[in] res cuvsResources_t opaque C handle
1016- * @param[in] params cuvsCagraIndexParams_t parameters controlling merge behavior
1043+ * @param[in] params cuvsCagraIndexParams_t parameters for the output index
10171044 * @param[in] indices Array of input cuvsCagraIndex_t handles to merge
10181045 * @param[in] num_indices Number of input indices
10191046 * @param[in] filter Filter that can be used to filter out vectors from the merged index
@@ -1034,6 +1061,34 @@ CUVS_EXPORT cuvsError_t cuvsCagraMerge(cuvsResources_t res,
10341061 cuvsDataset_t merged_dataset ,
10351062 cuvsCagraIndex_t output_index );
10361063
1064+ /**
1065+ * @brief Merge multiple CAGRA indices with explicit merge parameters.
1066+ *
1067+ * @param[in] res cuvsResources_t opaque C handle
1068+ * @param[in] params cuvsCagraIndexParams_t parameters for the output index
1069+ * @param[in] merge_params cuvsCagraMergeParams_t parameters controlling the merge algorithm, or
1070+ * NULL to use AUTO defaults
1071+ * @param[in] indices Array of input cuvsCagraIndex_t handles to merge
1072+ * @param[in] num_indices Number of input indices
1073+ * @param[in] filter Filter that can be used to filter out vectors from the merged index
1074+ * @param[out] merged_dataset Empty owning dataset handle. Merge first attempts to allocate and
1075+ * populate device storage with the same layout as the input indices. For
1076+ * an unfiltered merge, AUTO and REBUILD can fall back to host storage if
1077+ * device allocation fails; explicit FASTENER reports the allocation
1078+ * failure instead. Keep this dataset alive while using `output_index`.
1079+ * A host-backed output index must be updated with
1080+ * `cuvsCagraUpdateDataset` before device search.
1081+ * @param[out] output_index Output handle initialized with `cuvsCagraIndexCreate`
1082+ */
1083+ CUVS_EXPORT cuvsError_t cuvsCagraMergeWithParams (cuvsResources_t res ,
1084+ cuvsCagraIndexParams_t params ,
1085+ cuvsCagraMergeParams_t merge_params ,
1086+ cuvsCagraIndex_t * indices ,
1087+ size_t num_indices ,
1088+ cuvsFilter filter ,
1089+ cuvsDataset_t merged_dataset ,
1090+ cuvsCagraIndex_t output_index );
1091+
10371092/**
10381093 * @}
10391094 */
0 commit comments