Cagra
Source header: cuvs/neighbors/cagra.hpp
CAGRA index search parameters
neighbors::cagra::search_algo
CAGRA index search parameters
Values
CAGRA index build parameters
neighbors::vpq_params
Parameters for VPQ compression.
Fields
graph_build_params_t
CAGRA index build parameters
neighbors::cagra::hnsw_heuristic_type
A strategy for selecting the graph build parameters based on similar HNSW index parameters.
Define how cagra::index_params::from_hnsw_params should construct a graph to construct a graph that is to be converted to (used by) a CPU HNSW index.
Values
neighbors::cagra::index_params::graph_build_heuristic
Select the graph build algorithm and its parameters for a dataset.
This is the main CAGRA build heuristic: it chooses between NN-descent and IVF-PQ based on the dataset size and tunes their parameters based on the target intermediate graph degree and the requested build quality. It returns the graph_build_params variant only; the caller is responsible for setting graph_degree / intermediate_graph_degree.
Parameters
Returns
neighbors::cagra::index_params::from_dataset
Create CAGRA index parameters heuristically tuned for a dataset.
Returns default CAGRA index_params with graph_build_params selected by graph_build_heuristic for the given dataset.
Usage example:
Parameters
Returns
static cagra::index_params
neighbors::cagra::index_params::from_hnsw_params
Create a CAGRA index parameters compatible with HNSW index
- IMPORTANT NOTE *
The reference HNSW index and the corresponding from-CAGRA generated HNSW index will NOT produce exactly the same recalls and QPS for the same parameter ef. The graphs are different internally. Depending on the selected heuristics, the CAGRA-produced graph’s QPS-Recall curve may be shifted along the curve right or left. See the heuristics descriptions for more details.
Usage example:
Parameters
Returns
static cagra::index_params
Types
neighbors::graph_build_params::iterative_search_params
Parameters for the iterative CAGRA graph build algorithm.
Inherits from cagra::search_params so that all search tuning knobs (search_width, max_iterations, itopk_size, etc.) are available for controlling the search-and-optimize loop during graph construction. The defaults are tuned for the build loop (e.g. search_width=1, max_iterations=8) and may differ from the regular search defaults.
neighbors::graph_build_params::ace_params
Specialized parameters for ACE (Augmented Core Extraction) graph build
Fields
CAGRA index extend parameters
neighbors::cagra::extend_params
CAGRA index extend parameters
Fields
CAGRA index type
neighbors::cagra::index
CAGRA index.
The index stores the dataset and a kNN graph in device memory.
neighbors::cagra::index::metric
Distance metric used for clustering.
Returns
neighbors::cagra::index::size
Total length of the index (number of vectors).
Returns
IdxT
neighbors::cagra::index::dim
Dimensionality of the data.
Returns
uint32_t
neighbors::cagra::index::graph_degree
Graph degree
Returns
uint32_t
neighbors::cagra::index::graph_size
Number of rows represented by the graph.
Returns
IdxT
neighbors::cagra::index::dataset
Non-owning dataset binding stored by the index.
Returns
DatasetViewT const&
neighbors::cagra::index::graph
neighborhood graph [size, graph-degree]
Returns
raft::device_matrix_view<const graph_index_type, int64_t, raft::row_major>
neighbors::cagra::index::source_indices
Mapping from internal graph node indices to the original user-provided indices.
Returns
std::optional<raft::device_vector_view<const index_type, int64_t>>
neighbors::cagra::index::dataset_fd
Get the dataset file descriptor (for disk-backed index)
Returns
const std::optional<cuvs::util::file_descriptor>&
neighbors::cagra::index::graph_fd
Get the graph file descriptor (for disk-backed index)
Returns
const std::optional<cuvs::util::file_descriptor>&
neighbors::cagra::index::mapping_fd
Get the mapping file descriptor (for disk-backed index)
Returns
const std::optional<cuvs::util::file_descriptor>&
neighbors::cagra::index::dataset_norms
Dataset norms for cosine distance [size]
Returns
std::optional<raft::device_vector_view<const float, int64_t>>
neighbors::cagra::index::index
Parameters
Returns
void
Additional overload: neighbors::cagra::index::index
Construct a graph-only index with a zero-row dataset view placeholder.
Parameters
Returns
explicit
Additional overload: neighbors::cagra::index::index
Construct an index from a dataset_view and knn_graph.
Stores a shallow copy of the dataset view. The index stores a non-owning view; the caller must keep the underlying host or device storage alive for the index lifetime.
Example — non-owning make_device_padded_dataset_view (wraps an existing device matrix; that matrix must outlive the index):
Example — owning make_device_padded_dataset returns owning storage (std::unique_ptr). You must keep that object alive (e.g. hold the unique_ptr in a variable or member) for as long as the index uses the dataset; the index does not take ownership of the buffer.
Parameters
Returns
void
neighbors::cagra::index::update_graph
Replace the graph with a new graph.
Since the new graph is a device array, we store a reference to that, and it is the caller’s responsibility to ensure that knn_graph stays alive as long as the index.
Parameters
Returns
void
Additional overload: neighbors::cagra::index::update_graph
Replace the graph by taking ownership of an existing device matrix.
Parameters
Returns
void
Additional overload: neighbors::cagra::index::update_graph
Replace the graph with a new graph.
We create a copy of the graph on the device. The index manages the lifetime of this copy.
Parameters
Returns
void
neighbors::cagra::index::update_source_indices
Replace the source indices with a new source indices taking the ownership of the passed vector.
Parameters
Returns
void
Additional overload: neighbors::cagra::index::update_source_indices
Copy the provided source indices into the index.
Parameters
Returns
void
neighbors::cagra::index::update_dataset
Update the dataset from a disk file using a file descriptor.
This method configures the index to use a disk-based dataset. The dataset file should contain a numpy header followed by vectors in row-major format. The number of rows and dimensionality are read from the numpy header.
Parameters
Returns
void
Additional overload: neighbors::cagra::index::update_graph
Update the graph from a disk file using a file descriptor.
This method configures the index to use a disk-based graph. The graph file should contain a numpy header followed by neighbor indices in row-major format. The number of rows and graph degree are read from the numpy header.
Parameters
Returns
void
neighbors::cagra::index::update_mapping
Update the dataset mapping from a disk file using a file descriptor.
This method configures the index to use a disk-based dataset mapping. The mapping file should contain a numpy header followed by index mappings.
Parameters
Returns
void
CAGRA index build functions
neighbors::cagra::build
Build directly from a device VPQ dataset view with FP16 codebooks.
A VPQ input can only use iterative CAGRA graph construction. When graph_build_params is std::monostate, iterative construction is selected automatically; explicitly selecting another graph builder is an error. The metric must be L2Expanded, PQ codes must be 8-bit, and the PQ subvector length must be 2, 4, or 8.
The returned index accepts float queries and stores a non-owning copy of dataset when attach_dataset_on_build is true. The owning device_vpq_dataset must outlive the index.
Parameters
Returns
cuvs::neighbors::cagra::device_pq_index<float, uint32_t, half>
built index<float, uint32_t, device_vpq_dataset_view<half, int64_t>>
Additional overload: neighbors::cagra::build
Build from a device padded dataset view (float).
Parameters
Returns
cuvs::neighbors::cagra::device_padded_index<float, uint32_t>
built device_padded_index<float, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device standard dataset view (float).
Parameters
Returns
cuvs::neighbors::cagra::device_standard_index<float, uint32_t>
built device_standard_index<float, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host padded dataset view (float).
Parameters
Returns
cuvs::neighbors::cagra::host_padded_index<float, uint32_t>
built host_padded_index<float, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host standard dataset view (float).
Parameters
Returns
cuvs::neighbors::cagra::host_standard_index<float, uint32_t>
built host_standard_index<float, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device padded dataset view (half).
Parameters
Returns
cuvs::neighbors::cagra::device_padded_index<half, uint32_t>
built device_padded_index<half, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device standard dataset view (half).
Parameters
Returns
cuvs::neighbors::cagra::device_standard_index<half, uint32_t>
built device_standard_index<half, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host padded dataset view (half).
Parameters
Returns
cuvs::neighbors::cagra::host_padded_index<half, uint32_t>
built host_padded_index<half, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host standard dataset view (half).
Parameters
Returns
cuvs::neighbors::cagra::host_standard_index<half, uint32_t>
built host_standard_index<half, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device padded dataset view (int8_t).
Parameters
Returns
cuvs::neighbors::cagra::device_padded_index<int8_t, uint32_t>
built device_padded_index<int8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device standard dataset view (int8_t).
Parameters
Returns
cuvs::neighbors::cagra::device_standard_index<int8_t, uint32_t>
built device_standard_index<int8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host padded dataset view (int8_t).
Parameters
Returns
cuvs::neighbors::cagra::host_padded_index<int8_t, uint32_t>
built host_padded_index<int8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host standard dataset view (int8_t).
Parameters
Returns
cuvs::neighbors::cagra::host_standard_index<int8_t, uint32_t>
built host_standard_index<int8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device padded dataset view (uint8_t).
Parameters
Returns
cuvs::neighbors::cagra::device_padded_index<uint8_t, uint32_t>
built device_padded_index<uint8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device standard dataset view (uint8_t).
Parameters
Returns
cuvs::neighbors::cagra::device_standard_index<uint8_t, uint32_t>
built device_standard_index<uint8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host padded dataset view (uint8_t).
Parameters
Returns
cuvs::neighbors::cagra::host_padded_index<uint8_t, uint32_t>
built host_padded_index<uint8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a host standard dataset view (uint8_t).
Parameters
Returns
cuvs::neighbors::cagra::host_standard_index<uint8_t, uint32_t>
built host_standard_index<uint8_t, uint32_t>
Additional overload: neighbors::cagra::build
Build from a device BBQ-quantized dataset view.
The kNN graph is built from the quantized codes alone, so the uncompressed vectors are never needed and peak memory is driven by the code size. Only nn-descent graph construction is available (IVF-PQ, iterative CAGRA search, and ACE all read uncompressed vectors), and the metric must be one of L2Expanded, L2SqrtExpanded, CosineExpanded, or InnerProduct and must match the metric the quantizer corrections were generated for.
The returned index cannot be searched: CAGRA has no BBQ search kernels. Call the type-changing update_dataset with an uncompressed device-padded dataset to search the resulting graph.
Parameters
Returns
cuvs::neighbors::cagra::device_bbq_index<float, uint32_t>
built device_bbq_index<float, uint32_t>
Additional overload: neighbors::cagra::build
cuvs::neighbors::device_bbq_dataset_view<float, int64_t> const& dataset)
Parameters
Returns
cuvs::neighbors::cagra::device_bbq_index<half, uint32_t>
Additional overload: neighbors::cagra::build
cuvs::neighbors::device_bbq_dataset_view<float, int64_t> const& dataset)
Parameters
Returns
cuvs::neighbors::cagra::device_bbq_index<int8_t, uint32_t>
Additional overload: neighbors::cagra::build
cuvs::neighbors::device_bbq_dataset_view<float, int64_t> const& dataset)
Parameters
Returns
cuvs::neighbors::cagra::device_bbq_index<uint8_t, uint32_t>
CAGRA extend functions
neighbors::cagra::extend
Add new vectors to a CAGRA index
Note: extend does not concatenate datasets. The caller owns the final dataset and must pre-populate a single padded device matrix of size (n_old + n_new) x dim (or overallocation with a view whose logical n_rows is n_old + n_new):
- rows
[0, new_start_row)hold the original vectors attached toidx - rows
[new_start_row, n_rows)hold the additional vectorsnew_start_rowmust equalidx.size()today. The library only extends the graph and rebinds the index toextended_dataset. Keep that view alive for the index lifetime.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::cagra::extend
Add new vectors to a CAGRA index. See the float overload for the full contract.
Parameters
Returns
void
Additional overload: neighbors::cagra::extend
Add new vectors to a CAGRA index. See the float overload for the full contract.
Parameters
Returns
void
Additional overload: neighbors::cagra::extend
Add new vectors to a CAGRA index. See the float overload for the full contract.
Parameters
Returns
void
CAGRA serialize functions
neighbors::cagra::serialized_dataset_kind
Dataset storage kind recorded in a serialized CAGRA index.
Values
neighbors::cagra::serialize
Save the index to file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
neighbors::cagra::deserialize
Load index from file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Write the index to an output stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from input stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Save the index to file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Write the index to an output stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from input stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Save the index to file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Write the index to an output stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from input stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Save the index to file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from file.
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Write the index to an output stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Load index from input stream
Experimental, both the API and the serialization format are subject to change.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
Additional overload: neighbors::cagra::deserialize
Parameters
Returns
void
neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream
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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Save a CAGRA build index in hnswlib base-layer-only serialized 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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream
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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Save a CAGRA build index in hnswlib base-layer-only serialized 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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream
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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Save a CAGRA build index in hnswlib base-layer-only serialized 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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream
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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Save a CAGRA build index in hnswlib base-layer-only serialized 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
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream.
Requires dataset — host builds do not store vectors in the index.
Parameters
Returns
void
Additional overload: neighbors::cagra::serialize_to_hnswlib
Write the CAGRA built index as a base layer HNSW index to an output stream.
Requires dataset — host builds do not store vectors in the index.
Parameters
Returns
void
CAGRA index build functions
neighbors::cagra::merge_algo
CAGRA index build functions
Values
neighbors::cagra::merge_params
C++ controls for physical CAGRA index merge.
Fields