cuVS Java API

cuVS Java API provides a Java based simple, efficient, and a robust vector search API.

Caution

This contains an experimental APIs and may change in upcoming releases.

Prerequisites

• CuVS libraries
• maven 3.9.6 or above
• JDK 22
• jextract for JDK 22 (If not already installed, the build script downloads it)

Building

The libcuvs C and C++ libraries are needed for this API. If libcuvs libraries have not been built and installed, use ./build.sh libcuvs java in the top level directory to build this API.

Alternatively, if libcuvs libraries are already built and you just want to build this API, please do ./build.sh java in the top level directory or just do ./build.sh in this directory.

Testing

Run ./build.sh --run-java-tests from this directory.

To run a single test suite:

cd cuvs-java/
mvn clean integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT

or, for a single test:

mvn clean integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT#testMergeStrategies

Be sure to set (manually, if needed) your LD_LIBRARY_PATH to include the directory with the appropriate (matching) version of libcuvs.so. Also, ensure that your panama bindings are up-to-date. They can be re-generated by running:

./panama-bindings/generate-bindings.sh

Tests run using a randomized runner. Specific failures can be reproduced running a test suite with a specific seed, by passing -Dtests.seed=42FC5CC6B4C6BA8E (where 42FC5CC6B4C6BA8E has to be replaced with your specific seed). It also possible to re-run a single test, but in this case it's necessary to pass the extended seed (suite:method), e.g.

mvn integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT#testFloatIndexing -Dtests.seed=66039A8CAFB9D3C9:449B6310296799E0

It is also possible to ask the test runner to run a specific test or suite multiple times, by passing -Dtests.iters=10 through the command line.

Filter bitset device pool

Multi-partition filters are uploaded lazily and share a process-lifetime device resource. By default, filter allocations use a growable RMM pool with a 4 MiB initial reservation. Applications can customize the initial size by setting:

java -Dcom.nvidia.cuvs.filterBitsetPoolSize=536870912 ...

Set the property before the first filter bitset is uploaded. The value is rounded up to RMM's 256-byte alignment requirement. It is an initial reservation rather than a memory cap, and the pool can grow as needed. Setting the property to 0 explicitly disables pooling and keeps the default workspace resource. An invalid or negative value produces a warning and uses the 4 MiB default.

This process-wide setting is independent of any host-side filter cache and is distinct from com.nvidia.cuvs.workspacePoolSize, which configures per-query search workspace pools.

Examples

A few starter examples of CAGRA, HNSW, and Bruteforce indexing and searching are provided in the examples directory.