Cagra
Source header: cuvs/neighbors/cagra.h
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraGraphBuildAlgo
Enum to denote which ANN algorithm is used to build CAGRA graph
Values
cuvsCagraHnswHeuristicType
A strategy for selecting the graph build parameters based on similar HNSW index parameters.
Define how cuvsCagraIndexParamsFromHnswParams should construct a graph to construct a graph that is to be converted to (used by) a CPU HNSW index.
Values
cuvsCagraCompressionParams
Parameters for PQ dataset compression.
The cuvsCagraCompressionParams name is retained for ABI compatibility and is planned for removal in the 27.02 ABI-breaking release. Use cuvsPqParams in new code.
Fields
cuvsAceParams
Parameters for ACE (Augmented Core Extraction) graph build.
ACE enables building indexes for datasets too large to fit in GPU memory by:
- Partitioning the dataset in core (closest) and augmented (second-closest) partitions using balanced k-means.
- Building sub-indexes for each partition independently
- Concatenating sub-graphs into a final unified index
Fields
cuvsCagraIndexParams
Supplemental parameters to build CAGRA Index
Fields
cuvsCagraMergeAlgo
Algorithm used to merge physical CAGRA indices.
Values
cuvsCagraMergeParams
Parameters controlling how physical CAGRA indices are merged.
Fields
cuvsCagraIndexParamsCreate
Allocate CAGRA Index params, and populate with default values
Parameters
Returns
cuvsCagraIndexParamsDestroy
De-allocate CAGRA Index params
Parameters
Returns
cuvsCagraMergeParamsCreate
Allocate CAGRA merge params and populate them with AUTO defaults.
Parameters
Returns
cuvsCagraMergeParamsDestroy
De-allocate CAGRA merge params.
Parameters
Returns
cuvsCagraCompressionParamsCreate
Allocate CAGRA Compression params, and populate with default values.
Deprecated: Use cuvsPqParamsCreate. This compatibility API is planned for removal in the 27.02 ABI-breaking release.
Parameters
Returns
cuvsCagraCompressionParamsDestroy
De-allocate CAGRA Compression params.
Deprecated: Use cuvsPqParamsDestroy. This compatibility API is planned for removal in the 27.02 ABI-breaking release.
Parameters
Returns
cuvsAceParamsCreate
Allocate ACE params, and populate with default values
Parameters
Returns
cuvsAceParamsDestroy
De-allocate ACE params
Parameters
Returns
cuvsCagraIndexParamsFromHnswParams
Create CAGRA index parameters similar to an HNSW index
This factory function creates CAGRA parameters that yield a graph compatible with an HNSW graph with the given parameters.
Parameters
Returns
cuvsCagraIndexParamsFromDataset
Create CAGRA index parameters heuristically tuned for a dataset
This factory function selects the graph build algorithm and its parameters based on the shape of the dataset.
Parameters
Returns
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraExtendParams
Supplemental parameters to extend CAGRA Index
Fields
cuvsCagraExtendParamsCreate
Allocate CAGRA Extend params, and populate with default values
Parameters
Returns
cuvsCagraExtendParamsDestroy
De-allocate CAGRA Extend params
Parameters
Returns
cuvsCagraExtend
Extend a CAGRA index with a caller-owned pre-concatenated padded dataset.
The caller must build extended_dataset as old \|\| new (size n_old + n_new) before calling. Rows [0, new_start_row) are the original vectors; rows [new_start_row, n_rows) are the additional vectors. new_start_row must equal the current index size. The library only extends the graph and rebinds the index to extended_dataset; keep that dataset alive for the index lifetime.
Parameters
Returns
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraSearchAlgo
Enum to denote algorithm used to search CAGRA Index
Values
cuvsCagraHashMode
Enum to denote Hash Mode used while searching CAGRA index
Values
cuvsCagraSearchParams
Supplemental parameters to search CAGRA index
Fields
cuvsCagraSearchParamsCreate
Allocate CAGRA search params, and populate with default values
Parameters
Returns
cuvsCagraSearchParamsDestroy
De-allocate CAGRA search params
Parameters
Returns
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraIndex
Struct holding the CAGRA index storage address and vector element dtype (DLPack-style)
Matches the usual cuVS C index pattern (addr + dtype). addr points at implementation-owned storage (not always a bare cagra::index*); free only via cuvsCagraIndexDestroy. dtype describes index vector elements for queries and template dispatch.
Fields
cuvsCagraIndexCreate
Allocate CAGRA index
Parameters
Returns
cuvsCagraIndexDestroy
De-allocate CAGRA index
Parameters
Returns
cuvsCagraIndexGetDims
Get dimension of the CAGRA index
Parameters
Returns
cuvsCagraIndexGetSize
Get size of the CAGRA index
Parameters
Returns
cuvsCagraIndexGetGraphDegree
Get graph degree of the CAGRA index
Parameters
Returns
cuvsCagraIndexGetDataset
Returns a view of the CAGRA dataset
This function returns a non-owning view of the CAGRA dataset. The output will be referencing device memory that is directly used in CAGRA, without copying the dataset at all. This means that the output is only valid as long as the CAGRA index is alive, and once cuvsCagraIndexDestroy is called on the cagra index - the returned dataset view will be invalid.
Note that the DLManagedTensor dataset returned will have an associated ‘deleter’ function that must be called when the dataset is no longer needed. This will free up host memory that stores the shape of the dataset view.
Parameters
Returns
cuvsCagraIndexGetGraph
Returns a view of the CAGRA graph
This function returns a non-owning view of the CAGRA graph. The output will be referencing device memory that is directly used in CAGRA, without copying the graph at all. This means that the output is only valid as long as the CAGRA index is alive, and once cuvsCagraIndexDestroy is called on the cagra index - the returned graph view will be invalid.
Note that the DLManagedTensor graph returned will have an associated ‘deleter’ function that must be called when the graph is no longer needed. This will free up host memory that stores the metadata for the graph view.
Parameters
Returns
cuvsCagraUpdateDataset
Update a CAGRA index with a device-padded or device-PQ dataset.
This is the centralized dataset update operation for C callers. The index’s opaque handle is rebound to an index over the supplied dataset layout. Device-padded and device-PQ datasets can be attached to any supported index layout. The caller retains ownership of dataset and must keep it alive while index uses it.
Parameters
Returns
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraBuild
Build a CAGRA index from a dataset handle. Acceptable underlying types are:
kDLDataType.code == kDLFloatandkDLDataType.bits = 32kDLDataType.code == kDLFloatandkDLDataType.bits = 16kDLDataType.code == kDLIntandkDLDataType.bits = 8kDLDataType.code == kDLUIntandkDLDataType.bits = 8
The memory space and layout dataset was constructed with select the C++ build overload. Build the handle with an owning factory or the matching dataset view factory (cuvsDatasetMakePaddedView, cuvsDatasetMakeStandardView, or cuvsDatasetMakeBbqView).
Note that a dataset residing in host memory produces a host-backed index, which must be made search-ready with cuvsCagraUpdateDataset (using a device-padded dataset) before calling cuvsCagraSearch.
A CUVS_DATASET_LAYOUT_PQ dataset created by cuvsDatasetMakePQ builds an iterative CAGRA-Q index. VPQ input requires L2Expanded and ITERATIVE_CAGRA_SEARCH (or AUTO_SELECT), and the VPQ dataset must outlive the index because the index stores a non-owning view. A CUVS_DATASET_LAYOUT_BBQ dataset builds a graph-only index; attach a searchable dataset with cuvsCagraUpdateDataset before search.
Parameters
Returns
C API for CUDA ANN Graph-based nearest neighbor search
cuvsCagraSearch
Search a CAGRA index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged. It is also important to note that the CAGRA Index must have been built with the same type of queries, such that index.dtype.code == queries.dl_tensor.dtype.code Types for input are:
queries: a.kDLDataType.code == kDLFloatandkDLDataType.bits = 32b.kDLDataType.code == kDLFloatandkDLDataType.bits = 16c.kDLDataType.code == kDLIntandkDLDataType.bits = 8d.kDLDataType.code == kDLUIntandkDLDataType.bits = 8neighbors:kDLDataType.code == kDLUIntandkDLDataType.bits = 32orkDLDataType.code == kDLIntandkDLDataType.bits = 64distances:kDLDataType.code == kDLFloatandkDLDataType.bits = 32
Parameters
Returns
cuvsCagraSearchMultiPartition
Search multiple CAGRA index partitions concurrently and return the global top-k per query.
For each query row, the function searches all partitions in parallel into an internal intermediate buffer, applies per-partition distance post-processing, runs a batched top-k merge across partitions, and writes the final outputs to the caller-supplied device tensors. All work is submitted to the CUDA stream associated with res; use cuvsStreamSync to wait for completion.
The index element type may be float32, float16, int8, or uint8. All partitions must share the same element type, and the queries must use that same type.
Parameters
Returns
CAGRA C-API serialize functions
cuvsCagraSerializeGraph
Save the CAGRA graph to file without its dataset.
This supports dense, PQ-backed, and BBQ-built indexes. The serialized file does not contain vector data. After deserialization the index cannot be searched until a compatible dataset is attached with cuvsCagraUpdateDataset.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
cuvsCagraSerializeGraphAndDataset
Save the CAGRA graph and its attached dataset to file.
The index stores a non-owning dataset view. The caller must keep the memory of the dataset backing that view alive while this function runs. Returns CUVS_ERROR without modifying the destination file if the index has no attached dataset. PQ and BBQ datasets are not serialized by this function.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
cuvsCagraSerializeToHnswlib
Save the CAGRA index to file in hnswlib format.
NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
cuvsCagraDeserializeGraph
Load the CAGRA graph from file without retaining a serialized dataset.
This succeeds whether or not the file contains a dataset. Use cuvsCagraUpdateDataset to attach a caller-owned device-padded or device-PQ dataset before searching the graph-only index.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
cuvsCagraDeserializeGraphAndDataset
Load the CAGRA graph and dataset from file.
The returned owning dataset preserves the serialized host/device memory type and standard/padded layout. The index stores a non-owning view into it, so the caller must keep the dataset alive while the index uses it and destroy it separately with cuvsDatasetDestroy. Only a device-padded result is immediately searchable through the C API; attach a caller-owned device-padded view with cuvsCagraUpdateDataset for any other kind. The output pointer must point to a null handle on entry; deserialization acts as a factory and transfers ownership of the allocated dataset handle on success. Returns CUVS_ERROR when the file has no dataset; the index and output handle are unchanged on failure.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
cuvsCagraIndexFromArgs
Load index from a dataset and graph
Parameters
Returns
CAGRA C-API merge functions
cuvsCagraMerge
Merge multiple CAGRA indices into a single CAGRA index.
All input indices must have been built with the same data type (index.dtype) and have the same dimensionality (index.dims). The merged index uses the output parameters specified in cuvsCagraIndexParams. The merge algorithm is selected automatically.
Input indices must have:
index.dtype.codeandindex.dtype.bitsmatching across all indices.- Supported data types for indices: a.
kDLFloatwithbits = 32b.kDLFloatwithbits = 16c.kDLIntwithbits = 8d.kDLUIntwithbits = 8
The resulting output index will have the same data type as the input indices.
Example:
Parameters
Returns
cuvsCagraMergeWithParams
Merge multiple CAGRA indices with explicit merge parameters.
Parameters
Returns