Installation via Maven Central is not supported due to Continuous Delivery complexity and poor support for native builds. Gradle installation is the recommended approach. For the most up-to-date version, the following Groovy script will download a "fat JAR" containing builds for Linux, Windows, macOS, and Android, compatible with all common hardware platforms:
repositories {
mavenCentral()
// Custom repository for USearch JAR
flatDir {
dirs 'lib'
}
}
// Task to download USearch JAR from GitHub releases
task downloadUSearchJar {
doLast {
def usearchVersion = '2.24.0'
def usearchUrl = "https://github.com/unum-cloud/usearch/releases/download/v${usearchVersion}/usearch-${usearchVersion}.jar"
def usearchFile = file("lib/usearch-${usearchVersion}.jar")
usearchFile.parentFile.mkdirs()
if (!usearchFile.exists()) {
new URL(usearchUrl).withInputStream { i ->
usearchFile.withOutputStream { it << i }
}
println "Downloaded USearch JAR: ${usearchFile.name}"
}
}
}
// Make compilation depend on downloading USearch
compileJava.dependsOn downloadUSearchJar
dependencies {
// USearch JAR from local lib directory (downloaded automatically)
implementation name: 'usearch', version: '2.24.0', ext: 'jar'
}import cloud.unum.usearch.Index;
public class Main {
public static void main(String[] args) {
try (Index index = new Index.Config()
.metric(Index.Metric.COSINE) // Or "cos"
.quantization(Index.Quantization.FLOAT32) // Or "f32"
.dimensions(3)
.capacity(100)
.build()) {
// Add to Index
float[] vector = {0.1f, 0.2f, 0.3f};
index.add(42L, vector);
// Search
long[] keys = index.search(new float[]{0.1f, 0.2f, 0.3f}, 10);
for (long key : keys) {
System.out.println("Found key: " + key);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}To save and load the index from disk, use the following methods:
index.save("index.usearch");
index.load("index.usearch");
index.view("index.usearch");It is generally not recommended to use HNSW indexes in case of frequent removals or major distribution shifts. For small updates, you can use the following methods:
float[] vector = index.get(42L);
boolean removed = index.remove(42L);
boolean renamed = index.rename(43L, 42L);To obtain metadata:
long size = index.size();
long capacity = index.capacity();
long dimensions = index.dimensions();
long connectivity = index.connectivity();USearch supports hardware-agnostic f64, f32, and i8 quantization for memory efficiency and performance optimization.
// 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
}USearch automatically detects batch operations when vector arrays contain multiple concatenated vectors:
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
}The USearch index is thread-safe and supports high-performance concurrent operations:
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;
}