Add: Overloaded Java APIs

Author: ashvardanian

CONTRIBUTING.md

@@ -427,32 +427,29 @@ java -cp "$(pwd)/build/classes/java/main" -Djava.library.path="$(pwd)/build/libs
 Or step by-step:
 
 ```sh
-cd java/cloud/unum/usearch
-javac -h . Index.java NativeUtils.java
+javac -cp java -h java/cloud/unum/usearch/ java/cloud/unum/usearch/Index.java
 
 # Ensure JAVA_HOME system environment variable has been set
 # e.g. export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
 
 # Ubuntu:
-g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux -I../../../../include cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
-g++ -shared -fPIC -o libusearch.so cloud_unum_usearch_Index.o -lc
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux -Iinclude java/cloud/unum/usearch/cloud_unum_usearch_Index.cpp -o java/cloud/unum/usearch/cloud_unum_usearch_Index.o
+g++ -shared -fPIC -o java/cloud/unum/usearch/libusearch.so java/cloud/unum/usearch/cloud_unum_usearch_Index.o -lc
 
 # Windows
-g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 cloud_unum_usearch_Index.cpp -I..\..\..\..\include -o cloud_unum_usearch_Index.o
-g++ -shared -o USearchJNI.dll cloud_unum_usearch_Index.o -Wl,--add-stdcall-alias
+g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 java\cloud\unum\usearch\cloud_unum_usearch_Index.cpp -Iinclude -o java\cloud\unum\usearch\cloud_unum_usearch_Index.o
+g++ -shared -o java\cloud\unum\usearch\USearchJNI.dll java\cloud\unum\usearch\cloud_unum_usearch_Index.o -Wl,--add-stdcall-alias
 
 # MacOS
 g++ -std=c++11 -c -fPIC \
-    -I../../../../include \
-    -I../../../../fp16/include \
-    -I../../../../simsimd/include \
-    -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
-g++ -dynamiclib -o libusearch.dylib cloud_unum_usearch_Index.o -lc
-
-# Run linking to that directory
-cd ../../../..
-cp cloud/unum/usearch/libusearch.* .
-java -cp . -Djava.library.path="$(pwd)" cloud.unum.usearch.Index
+    -Iinclude \
+    -Ifp16/include \
+    -Isimsimd/include \
+    -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin java/cloud/unum/usearch/cloud_unum_usearch_Index.cpp -o java/cloud/unum/usearch/cloud_unum_usearch_Index.o
+g++ -dynamiclib -o java/cloud/unum/usearch/libusearch.dylib java/cloud/unum/usearch/cloud_unum_usearch_Index.o -lc
+
+# Run from project root
+java -cp java -Djava.library.path="java/cloud/unum/usearch" cloud.unum.usearch.Index
 ```
 
 Or using CMake:

README.md

@@ -357,7 +357,7 @@ In some cases, like Batch operations, feature parity is meaningless, as the host
 | Add, search, remove     |   ✅    |    ✅     |   ✅   |   ✅   |     ✅      |   ✅   |   ✅    |   ✅   |
 | Save, load, view        |   ✅    |    ✅     |   ✅   |   ✅   |     ✅      |   ✅   |   ✅    |   ✅   |
 | User-defined metrics    |   ✅    |    ✅     |   ✅   |   ❌   |     ❌      |   ❌   |   ❌    |   ❌   |
-| Batch operations        |   ❌    |    ✅     |   ❌   |   ❌   |     ✅      |   ❌   |   ❌    |   ❌   |
+| Batch operations        |   ❌    |    ✅     |   ❌   |   ✅   |     ✅      |   ❌   |   ❌    |   ❌   |
 | Filter predicates       |   ✅    |    ❌     |   ✅   |   ❌   |     ❌      |   ✅   |   ❌    |   ❌   |
 | Joins                   |   ✅    |    ✅     |   ❌   |   ❌   |     ❌      |   ❌   |   ❌    |   ❌   |
 | Variable-length vectors |   ✅    |    ❌     |   ❌   |   ❌   |     ❌      |   ❌   |   ❌    |   ❌   |

java/README.md

@@ -71,3 +71,113 @@ long capacity = index.capacity();
 long dimensions = index.dimensions();
 long connectivity = index.connectivity();
 ```
+
+## Multiple Data Types and Quantization
+
+USearch supports hardware-agnostic `f64`, `f32`, and `i8` quantization for memory efficiency and performance optimization.
+
+```java
+// Double precision (f64) for highest accuracy
+try (Index doubleIndex = new Index.Config()
+        .metric("cos")
+        .dimensions(3)
+        .quantization("f64")
+        .build()) {
+    
+    double[] vector = {0.1, 0.2, 0.3};
+    doubleIndex.add(42L, vector);
+    
+    double[] buffer = new double[3];
+    doubleIndex.getInto(42L, buffer); // Memory-efficient retrieval
+}
+
+// Byte precision (i8) for memory efficiency  
+try (Index byteIndex = new Index.Config()
+        .metric("cos")
+        .dimensions(3)
+        .quantization("i8")
+        .build()) {
+    
+    byte[] vector = {10, 20, 30};
+    byteIndex.add(42L, vector);
+    
+    byte[] buffer = new byte[3];
+    byteIndex.getInto(42L, buffer); // Memory-efficient retrieval
+}
+```
+
+## Batch Operations
+
+USearch automatically detects batch operations when vector arrays contain multiple concatenated vectors:
+
+```java
+try (Index index = new Index.Config()
+        .metric("cos")
+        .dimensions(2)
+        .build()) {
+    
+    // Batch add: 3 vectors in one call
+    float[] batchVectors = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f};
+    index.add(100L, batchVectors); // Adds vectors at keys 100, 101, 102
+    
+    // Verify batch was added correctly
+    System.out.println("Index size: " + index.size()); // Output: 3
+}
+```
+
+## Concurrent Operations
+
+The USearch index is thread-safe and supports high-performance concurrent operations:
+
+```java
+import java.util.concurrent.*;
+
+try (Index index = new Index.Config()
+        .metric("cos")
+        .dimensions(4)
+        .capacity(10000)
+        .build()) {
+    
+    ExecutorService executor = Executors.newFixedThreadPool(8);
+    
+    // Concurrent additions from multiple threads
+    CompletableFuture<Void>[] addTasks = new CompletableFuture[4];
+    for (int t = 0; t < 4; t++) {
+        final int threadId = t;
+        addTasks[t] = CompletableFuture.runAsync(() -> {
+            for (int i = 0; i < 1000; i++) {
+                long key = threadId * 1000L + i;
+                float[] vector = generateRandomVector(4);
+                index.add(key, vector);
+            }
+        }, executor);
+    }
+    
+    // Concurrent searches while adding
+    CompletableFuture<Void>[] searchTasks = new CompletableFuture[4];
+    for (int t = 0; t < 4; t++) {
+        searchTasks[t] = CompletableFuture.runAsync(() -> {
+            for (int i = 0; i < 100; i++) {
+                float[] query = generateRandomVector(4);
+                long[] results = index.search(query, 10);
+                processResults(results);
+            }
+        }, executor);
+    }
+    
+    // Wait for all operations to complete
+    CompletableFuture.allOf(addTasks).join();
+    CompletableFuture.allOf(searchTasks).join();
+    executor.shutdown();
+    
+    System.out.println("Final index size: " + index.size());
+}
+
+private static float[] generateRandomVector(int dimensions) {
+    float[] vector = new float[dimensions];
+    for (int i = 0; i < dimensions; i++) {
+        vector[i] = (float) Math.random();
+    }
+    return vector;
+}
+```

java/cloud/unum/usearch/Index.java

@@ -241,7 +241,7 @@ public void add(long key, float vector[]) {
     if (c_ptr == 0) {
       throw new IllegalStateException("Index already closed");
     }
-    c_add(c_ptr, key, vector);
+    c_add_f32(c_ptr, key, vector);
   }
 
   /**
@@ -255,7 +255,7 @@ public long[] search(float vector[], long count) {
     if (c_ptr == 0) {
       throw new IllegalStateException("Index already closed");
     }
-    return c_search(c_ptr, vector, count);
+    return c_search_f32(c_ptr, vector, count);
   }
 
   /**
@@ -272,6 +272,108 @@ public float[] get(long key) {
     return c_get(c_ptr, key);
   }
 
+  /**
+   * Adds a double precision vector with a specified key to the index.
+   *
+   * @param key    the key associated with the vector
+   * @param vector the double precision vector data
+   */
+  public void add(long key, double vector[]) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    c_add_f64(c_ptr, key, vector);
+  }
+
+  /**
+   * Searches for closest vectors to the specified double precision query vector.
+   *
+   * @param vector the double precision query vector data
+   * @param count  the number of nearest neighbors to search
+   * @return an array of keys of the nearest neighbors
+   */
+  public long[] search(double vector[], long count) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    return c_search_f64(c_ptr, vector, count);
+  }
+
+  /**
+   * Adds an int8 quantized vector with a specified key to the index.
+   *
+   * @param key    the key associated with the vector
+   * @param vector the int8 quantized vector data
+   */
+  public void add(long key, byte vector[]) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    c_add_i8(c_ptr, key, vector);
+  }
+
+  /**
+   * Searches for closest vectors to the specified int8 quantized query vector.
+   *
+   * @param vector the int8 quantized query vector data
+   * @param count  the number of nearest neighbors to search
+   * @return an array of keys of the nearest neighbors
+   */
+  public long[] search(byte vector[], long count) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    return c_search_i8(c_ptr, vector, count);
+  }
+
+  /**
+   * Retrieves the vector at the specified key and populates the provided float
+   * buffer.
+   *
+   * @param key    key to lookup.
+   * @param buffer buffer to populate with vector data.
+   * @throws IllegalArgumentException if key is not available or buffer size is
+   *                                  incorrect.
+   */
+  public void getInto(long key, float[] buffer) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    c_get_into_f32(c_ptr, key, buffer);
+  }
+
+  /**
+   * Retrieves the vector at the specified key and populates the provided double
+   * buffer.
+   *
+   * @param key    key to lookup.
+   * @param buffer buffer to populate with vector data.
+   * @throws IllegalArgumentException if key is not available or buffer size is
+   *                                  incorrect.
+   */
+  public void getInto(long key, double[] buffer) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    c_get_into_f64(c_ptr, key, buffer);
+  }
+
+  /**
+   * Retrieves the vector at the specified key and populates the provided byte
+   * buffer.
+   *
+   * @param key    key to lookup.
+   * @param buffer buffer to populate with vector data.
+   * @throws IllegalArgumentException if key is not available or buffer size is
+   *                                  incorrect.
+   */
+  public void getInto(long key, byte[] buffer) {
+    if (c_ptr == 0) {
+      throw new IllegalStateException("Index already closed");
+    }
+    c_get_into_i8(c_ptr, key, buffer);
+  }
+
   /**
    * Saves the index to a file.
    *
@@ -573,12 +675,6 @@ private static native long c_create(
 
   private static native void c_reserve(long ptr, long capacity);
 
-  private static native void c_add(long ptr, long key, float vector[]);
-
-  private static native long[] c_search(long ptr, float vector[], long count);
-
-  private static native float[] c_get(long ptr, long key);
-
   private static native void c_save(long ptr, String path);
 
   private static native void c_load(long ptr, String path);
@@ -588,4 +684,26 @@ private static native long c_create(
   private static native boolean c_remove(long ptr, long key);
 
   private static native boolean c_rename(long ptr, long from, long to);
+
+  private static native float[] c_get(long ptr, long key);
+
+  // Overloaded methods:
+  private static native void c_add_f32(long ptr, long key, float vector[]);
+
+  private static native void c_add_f64(long ptr, long key, double vector[]);
+
+  private static native void c_add_i8(long ptr, long key, byte vector[]);
+
+  private static native long[] c_search_f32(long ptr, float vector[], long count);
+
+  private static native long[] c_search_f64(long ptr, double vector[], long count);
+
+  private static native long[] c_search_i8(long ptr, byte vector[], long count);
+
+  private static native void c_get_into_f32(long ptr, long key, float buffer[]);
+
+  private static native void c_get_into_f64(long ptr, long key, double buffer[]);
+
+  private static native void c_get_into_i8(long ptr, long key, byte buffer[]);
+
 }