[Java]Support for merge API for CAGRA index

Author: punAhuja

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java

@@ -52,6 +52,17 @@ public interface CagraIndex {
      */
     SearchResults search(CagraQuery query) throws Throwable;
 
+    /**
+     * Merges multiple CAGRA indices into a single CAGRA index.
+     *
+     * @param indices Array of CAGRA indices to merge
+     * @param mergeParams Parameters for the merge operation
+     * @return A new merged CAGRA index
+     * @throws Throwable if an error occurs during merging
+     * @since 25.06
+     */
+    CagraIndex merge(CagraIndex[] indices, CagraMergeParams mergeParams) throws Throwable;
+
     /**
      * A method to persist a CAGRA index using an instance of {@link OutputStream}
      * for writing index bytes.

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraMergeParams.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.nvidia.cuvs;
+
+/**
+ * Parameters for merging CAGRA indices.
+ *
+ * @since 25.06
+ */
+public class CagraMergeParams {
+    
+    /**
+     * Strategy for merging CAGRA indices.
+     */
+    public enum MergeStrategy {
+        /**
+         * Merge indices physically by combining their data structures.
+         */
+        PHYSICAL(0),
+        
+        /**
+         * Merge indices logically (if supported).
+         */
+        LOGICAL(1);
+
+        private final int value;
+
+        MergeStrategy(int value) {
+            this.value = value;
+        }
+
+        /**
+         * Get the integer value of the strategy for native code.
+         *
+         * @return the integer value
+         */
+        public int getValue() {
+            return value;
+        }
+    }
+
+    private final CagraIndexParams outputIndexParams;
+    private final MergeStrategy strategy;
+
+    /**
+     * Creates a new instance of CagraMergeParams.
+     *
+     * @param outputIndexParams parameters for the output merged index
+     * @param strategy the merge strategy to use
+     */
+    public CagraMergeParams(CagraIndexParams outputIndexParams, MergeStrategy strategy) {
+        this.outputIndexParams = outputIndexParams;
+        this.strategy = strategy;
+    }
+
+    /**
+     * Gets the output index parameters.
+     *
+     * @return the output index parameters
+     */
+    public CagraIndexParams getOutputIndexParams() {
+        return outputIndexParams;
+    }
+
+    /**
+     * Gets the merge strategy.
+     *
+     * @return the merge strategy
+     */
+    public MergeStrategy getStrategy() {
+        return strategy;
+    }
+} 

java/cuvs-java/src/main/java22/com/nvidia/cuvs/internal/CagraIndexImpl.java

@@ -42,6 +42,7 @@
 import com.nvidia.cuvs.CagraIndex;
 import com.nvidia.cuvs.CagraIndexParams;
 import com.nvidia.cuvs.CagraIndexParams.CagraGraphBuildAlgo;
+import com.nvidia.cuvs.CagraMergeParams;
 import com.nvidia.cuvs.CagraQuery;
 import com.nvidia.cuvs.CagraSearchParams;
 import com.nvidia.cuvs.CuVSResources;
@@ -87,6 +88,15 @@ public class CagraIndexImpl implements CagraIndex {
   private static final MethodHandle serializeCAGRAIndexToHNSWMethodHandle = downcallHandle("serialize_cagra_index_to_hnsw",
       FunctionDescriptor.ofVoid(ADDRESS, ADDRESS, ADDRESS, ADDRESS));
 
+  private static final MethodHandle mergeParamsCreateMethodHandle = downcallHandle("cuvsCagraMergeParamsCreate",
+      FunctionDescriptor.of(C_INT, ADDRESS));
+
+  private static final MethodHandle mergeParamsDestroyMethodHandle = downcallHandle("cuvsCagraMergeParamsDestroy",
+      FunctionDescriptor.of(C_INT, ADDRESS));
+
+  private static final MethodHandle mergeMethodHandle = downcallHandle("cuvsCagraMerge",
+      FunctionDescriptor.of(C_INT, ADDRESS, ADDRESS, C_INT, ADDRESS, ADDRESS));
+
   private final float[][] dataset;
   private final CuVSResourcesImpl resources;
   private final CagraIndexParams cagraIndexParameters;
@@ -127,6 +137,21 @@ private CagraIndexImpl(InputStream inputStream, CuVSResourcesImpl resources) thr
     this.cagraIndexReference = deserialize(inputStream);
   }
 
+  /**
+   * Constructor for creating a CagraIndexImpl from an existing index reference
+   * Used internally by merge operation
+   *
+   * @param indexRef The index reference to use
+   * @param resources The CuVS resources instance
+   */
+  private CagraIndexImpl(IndexReference indexRef, CuVSResourcesImpl resources) {
+    this.cagraIndexParameters = null;
+    this.cagraCompressionParams = null;
+    this.dataset = null;
+    this.resources = resources;
+    this.cagraIndexReference = indexRef;
+  }
+
   private void checkNotDestroyed() {
     if (destroyed) {
       throw new IllegalStateException("destroyed");
@@ -230,6 +255,70 @@ public SearchResults search(CagraQuery query) throws Throwable {
         distancesMemorySegment, topK, query.getMapping(), numQueries);
   }
 
+  /**
+   * Merges multiple CAGRA indices into a single CAGRA index.
+   *
+   * @param indices Array of CAGRA indices to merge
+   * @param mergeParams Parameters for the merge operation
+   * @return A new merged CAGRA index
+   * @throws Throwable if an error occurs during merging
+   */
+  @Override
+  public CagraIndex merge(CagraIndex[] indices, CagraMergeParams mergeParams) throws Throwable {
+    checkNotDestroyed();
+    Objects.requireNonNull(indices, "indices cannot be null");
+    Objects.requireNonNull(mergeParams, "mergeParams cannot be null");
+
+    if (indices.length == 0) {
+      throw new IllegalArgumentException("indices array cannot be empty");
+    }
+
+    try (var arena = Arena.ofConfined()) {
+      // Create merge params
+      MemorySegment paramsPtr = arena.allocate(ADDRESS);
+      MemorySegment returnValue = arena.allocate(C_INT);
+
+      mergeParamsCreateMethodHandle.invokeExact(paramsPtr);
+      checkError(returnValue.get(C_INT, 0L), "mergeParamsCreateMethodHandle");
+
+      // Get array of index pointers
+      MemorySegment[] indexPtrs = new MemorySegment[indices.length];
+      for (int i = 0; i < indices.length; i++) {
+        if (!(indices[i] instanceof CagraIndexImpl)) {
+          throw new IllegalArgumentException("All indices must be CagraIndexImpl instances");
+        }
+        indexPtrs[i] = ((CagraIndexImpl)indices[i]).cagraIndexReference.getMemorySegment();
+      }
+
+      // Create array segment for index pointers
+      SequenceLayout indexPtrLayout = MemoryLayout.sequenceLayout(indices.length, ADDRESS);
+      MemorySegment indexPtrArray = arena.allocate(indexPtrLayout);
+      for (int i = 0; i < indices.length; i++) {
+        indexPtrArray.setAtIndex(ADDRESS, i, indexPtrs[i]);
+      }
+
+      // Create output index pointer
+      MemorySegment outputIndexPtr = arena.allocate(ADDRESS);
+
+      // Call merge function
+      mergeMethodHandle.invokeExact(
+        resources.getMemorySegment(),
+        indexPtrArray,
+        indices.length,
+        paramsPtr,
+        outputIndexPtr
+      );
+      checkError(returnValue.get(C_INT, 0L), "mergeMethodHandle");
+
+      // Clean up merge params
+      mergeParamsDestroyMethodHandle.invokeExact(paramsPtr);
+      checkError(returnValue.get(C_INT, 0L), "mergeParamsDestroyMethodHandle");
+
+      // Create new CagraIndexImpl with merged index
+      return new CagraIndexImpl(new IndexReference(outputIndexPtr.get(ADDRESS, 0)), resources);
+    }
+  }
+
   @Override
   public void serialize(OutputStream outputStream) throws Throwable {
     Path p = Files.createTempFile(resources.tempDirectory(), UUID.randomUUID().toString(), ".cag");