Skip to navigation

CagraIndex

View as Markdown

Java package: com.nvidia.cuvs

public interface CagraIndex extends AutoCloseable

CagraIndex encapsulates a CAGRA index, along with methods to interact with it.

CAGRA is a graph-based nearest neighbors algorithm that was built from the ground up for GPU acceleration. CAGRA demonstrates state-of-the art index build and query performance for both small and large-batch sized search. Know more about this algorithm here

Public Members

setDelegate

public final void setDelegate(AutoCloseable delegate, long handleAddress)

Internal wiring hook used by the Java wrapper implementation.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:34

isPresent

public final boolean isPresent()

Returns true when this view has a native handle.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:42

nativeHandleAddress

public final long nativeHandleAddress()

Internal accessor for native handle address.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:49

setDelegate

public final void setDelegate(AutoCloseable delegate)

Internal wiring hook used by the Java wrapper implementation.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:84

setDelegate

public final void setDelegate(AutoCloseable delegate, long handleAddress)

Internal wiring hook used by the Java wrapper implementation.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:91

isPresent

public final boolean isPresent()

Returns true when this handle owns native dataset storage.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:99

nativeHandleAddress

public final long nativeHandleAddress()

Internal accessor for native handle address.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:106

close

@Override void close() throws Exception

Invokes the native destroy_cagra_index to de-allocate the CAGRA index. Also attempts to close any dataset whose ownership transferred to this index during construction.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:137

SearchResults search(CagraQuery query) throws Throwable

Invokes the native search_cagra_index via the Panama API for searching a CAGRA index.

Parameters

NameDescription
queryan instance of CagraQuery holding the query vectors and other parameters

Returns

an instance of SearchResults containing the results

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:148

makePaddedDataset

PaddedDataset makePaddedDataset(CuVSMatrix dataset) throws Throwable

Create an owning padded dataset by allocating padded storage and copying dataset. Prefer this when the source matrix is not already padded to CAGRA’s required row stride (e.g. unaligned dimensions).

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:155

makePaddedDatasetView

PaddedDatasetView makePaddedDatasetView(CuVSMatrix dataset) throws Throwable

Create a caller-owned padded dataset view handle from a matrix that is already padded to CAGRA’s required row stride. For unpadded matrices use #makePaddedDataset(CuVSMatrix).

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:162

makeStandardDatasetView

StandardDatasetView makeStandardDatasetView(CuVSMatrix dataset) throws Throwable

Create a caller-owned standard dataset view handle from a matrix.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:165

updateDataset

void updateDataset(PaddedDatasetView datasetView) throws Throwable

Update this index with a caller-provided padded device dataset view and leave it search-ready in padded-device layout. The caller retains ownership of the underlying padded storage and must keep it alive while this index uses it.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:172

updateDataset

void updateDataset(PaddedDataset dataset) throws Throwable

Update this index with a caller-owned padded device dataset. The dataset must remain alive while this index uses it.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:178

getGraph

CuVSDeviceMatrix getGraph()

Returns the CAGRA graph

Returns

a CuVSDeviceMatrix encapsulating the native int (uint32_t) array used to represent the cagra graph

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:185

getGraphDegree

long getGraphDegree()

Returns the degree of the built CAGRA graph (its number of edges per node), which may be smaller than the requested graph_degree when the dataset is small enough that the build truncated it.

Returns

the built graph degree (graph().extent(1))

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:194

size

long size()

Returns the number of vectors in this index.

Returns

the number of rows of the indexed dataset

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:201

serialize

void serialize(OutputStream outputStream) throws Throwable

A method to persist a CAGRA index using an instance of OutputStream for writing index bytes.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes into

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:210

serialize

void serialize(OutputStream outputStream, int bufferLength) throws Throwable

A method to persist a CAGRA index using an instance of OutputStream for writing index bytes.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes into
bufferLengththe length of buffer to use for writing bytes. Default value is 1024

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:221

serialize

default void serialize(OutputStream outputStream, Path tempFile) throws Throwable

A method to persist a CAGRA index using an instance of OutputStream for writing index bytes.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes into
tempFilean intermediate Path where CAGRA index is written temporarily

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:232

serialize

void serialize(OutputStream outputStream, Path tempFile, int bufferLength) throws Throwable

A method to persist a CAGRA index using an instance of OutputStream and path to the intermediate temporary file.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes to
tempFilean intermediate Path where CAGRA index is written temporarily
bufferLengththe length of buffer to use for writing bytes. Default value is 1024

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:247

serializeToHNSW

void serializeToHNSW(OutputStream outputStream) throws Throwable

A method to create and persist HNSW index from CAGRA index using an instance of OutputStream and path to the intermediate temporary file.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes to

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:256

serializeToHNSW

void serializeToHNSW(OutputStream outputStream, int bufferLength) throws Throwable

A method to create and persist HNSW index from CAGRA index using an instance of OutputStream and path to the intermediate temporary file.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes to
bufferLengththe length of buffer to use for writing bytes. Default value is 1024

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:267

serializeToHNSW

default void serializeToHNSW(OutputStream outputStream, Path tempFile) throws Throwable

A method to create and persist HNSW index from CAGRA index using an instance of OutputStream and path to the intermediate temporary file.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes to
tempFilean intermediate Path where CAGRA index is written temporarily

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:278

serializeToHNSW

void serializeToHNSW(OutputStream outputStream, Path tempFile, int bufferLength) throws Throwable

A method to create and persist HNSW index from CAGRA index using an instance of OutputStream and path to the intermediate temporary file.

Parameters

NameDescription
outputStreaman instance of OutputStream to write the index bytes to
tempFilean intermediate Path where CAGRA index is written temporarily
bufferLengththe length of buffer to use for writing bytes. Default value is 1024

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:293

getCuVSResources

CuVSResources getCuVSResources()

Gets an instance of CuVSResources

Returns

an instance of CuVSResources

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:300

newBuilder

static Builder newBuilder(CuVSResources cuvsResources)

Creates a new Builder with an instance of CuVSResources.

Parameters

NameDescription
cuvsResourcesan instance of CuVSResources

Throws

TypeDescription
UnsupportedOperationExceptionif the provider does not cuvs

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:308

merge

static CagraIndex merge(CagraIndex[] indexes) throws Throwable

Merges multiple CAGRA indexes into a single index using default merge parameters.

Parameters

NameDescription
indexesArray of CAGRA indexes to merge

Returns

A new merged CAGRA index

Throws

TypeDescription
Throwableif an error occurs during the merge operation

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:320

merge

static CagraIndex merge(CagraIndex[] indexes, CagraIndexParams mergeParams) throws Throwable

Merges multiple CAGRA indexes into a single index with the specified merge parameters.

Parameters

NameDescription
indexesArray of CAGRA indexes to merge
mergeParamsParameters to control the merge operation, or null to use defaults

Returns

A new merged CAGRA index

Throws

TypeDescription
Throwableif an error occurs during the merge operation

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:332

merge

static CagraIndex merge(CagraIndex[] indexes, CagraIndexParams mergeParams, BitSet rowFilter) throws Throwable

Merges multiple CAGRA indexes into a single index, keeping only the rows selected by rowFilter.

The merge concatenates the input datasets in the order the indexes are given, so bit i of the filter refers to row i of that concatenation: bits 0 to indexes[0].size() - 1 address the first index, the bits that follow address the second, and so on. A set bit keeps the row; a clear bit drops it. The rows that survive keep their relative order and are packed together, so the merged index has one row per set bit.

Parameters

NameDescription
indexesArray of CAGRA indexes to merge
mergeParamsParameters to control the merge operation, or null to use defaults
rowFilterThe rows to keep, or null to keep all of them. A BitSet shorter than the total row count is valid: the rows beyond its logical length are treated as clear (dropped). A bit set at a position at or beyond the total row count throws IllegalArgumentException.

Returns

A new merged CAGRA index

Throws

TypeDescription
IllegalArgumentExceptionif rowFilter has a bit set beyond the last row, or if it is non-null but keeps no rows at all
Throwableif an error occurs during the merge operation

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:356

isPaddedDataset

static boolean isPaddedDataset(CuVSMatrix dataset)

Reports whether the rows of dataset already sit at the row stride CAGRA requires, which is the row length in bytes rounded up to a 16 byte boundary.

Use it to pick between the two padded dataset factories: a matrix that is already padded has to go through #makePaddedDatasetView(CuVSMatrix), because cuVS rejects a request to copy it into padded storage it already occupies, and one that is not has to go through #makePaddedDataset(CuVSMatrix).

Parameters

NameDescription
datasetthe matrix to inspect

Returns

true when the rows are already padded the way CAGRA requires

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:384

from

Builder from(InputStream inputStream)

Sets an instance of InputStream typically used when index deserialization is needed.

Parameters

NameDescription
inputStreaman instance of InputStream

Returns

an instance of this Builder

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:401

from

Builder from(InputStream inputStream, DeserializeDataset outDataset)

Sets an input stream and an empty caller-owned output handle for explicit dataset deserialization. The concrete output type must match the dataset layout stored in the serialized index. Keep outDataset alive while the built index is in use.

Parameters

NameDescription
inputStreaman instance of InputStream
outDatasetan empty PaddedDataset or StandardDataset

Returns

an instance of this Builder

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:412

from

Builder from(CuVSMatrix graph)

Sets a CAGRA graph instance to re-create an index from a previously built graph.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:418

withDataset

Builder withDataset(float[][] vectors)

Sets the dataset vectors for building the CagraIndex.

Parameters

NameDescription
vectorsa two-dimensional float array

Returns

an instance of this Builder

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:426

withDataset

Builder withDataset(CuVSMatrix dataset)

Sets the dataset for building the CagraIndex.

The caller retains ownership until a build that uses this dataset returns successfully. The returned index then owns the dataset, and the caller must leave it open until the index is closed. If the build fails or uses another configured input source, ownership remains with the caller.

Parameters

NameDescription
dataseta CuVSMatrix object containing the vectors

Returns

an instance of this Builder

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:439

withBbqDataset

Builder withBbqDataset(BbqQuantizer... quantizers)

Builds the graph from one or two encoded BBQ representations. An optional dense dataset supplied with #withDataset(CuVSMatrix) is attached before search; otherwise call CagraIndex#updateDataset(PaddedDatasetView) or CagraIndex#updateDataset(PaddedDataset) before searching.

The index stores views over the quantizer tensors rather than copying them, so they must stay open for as long as the index is in use. A dense dataset passed to #withDataset(CuVSMatrix) is owned by the index, as it is for a non-BBQ build, and is closed with it.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:452

withIndexParams

Builder withIndexParams(CagraIndexParams cagraIndexParameters)

Registers an instance of configured CagraIndexParams with this Builder.

Parameters

NameDescription
cagraIndexParametersAn instance of CagraIndexParams.

Returns

An instance of this Builder.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:461

build

CagraIndex build() throws Throwable

Builds and returns an instance of CagraIndex.

Returns

an instance of CagraIndex

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:468

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:26