Common
Source header: cuvs/neighbors/common.hpp
Approximate Nearest Neighbors Types
neighbors::index
The base for approximate KNN index structures.
neighbors::index_params
The base for KNN index parameters.
Fields
neighbors::MergeStrategy
Strategy for merging indices.
This enum is declared separately to avoid namespace pollution when including common.hpp. It provides a generic merge strategy that can be used across different index types.
Values
Types
neighbors::dataset
Tags selecting dataset representation for dataset / dataset_view.
Each container defines nested owning_storage then view_storage (aliases into detail::* storage types shared by device/host). Accessibility (device vs host) is selected by the Accessor template parameter on dataset / dataset_view, not by duplicating containers. Layout kinds: empty, padded, standard, VPQ. dataset / dataset_view only express ownership vs view.
math_type
Floating-point type used for VQ/PQ codebooks (rows are still uint8 codes).
neighbors::dataset_view_kind_of
Primary template returns unknown so traits safely return false for non-dataset-view types.
Fields
neighbors::dataset_view_is_device_accessible
True when the dataset view accessor is device-accessible.
neighbors::with_accessor
Generic accessor retargeting while preserving the dataset tag/layout and value/index types:
dataset<Tag, DataT, IdxT, OldAccessor> -> dataset<Tag, DataT, IdxT, NewAccessor> dataset_view<Tag, DataT, IdxT, OldAccessor> -> dataset_view<Tag, DataT, IdxT, NewAccessor>
neighbors::to_device_accessor
Map any host accessor to its device counterpart (same payload policy).
neighbors::device_counterpart
Maps a host dataset view type to its device-resident counterpart.
neighbors::cagra_view_element_type
Element type T for cagra::build(res, params, dataset_view) (deduced, not a template arg).
neighbors::ivf::list_base
Abstract base class for IVF list data.
This allows polymorphic access to list data regardless of the underlying layout.
TODO: Make this struct internal (tracking issue: https://github.com/NVIDIA/cuvs/issues/1726)
neighbors::ivf::list
The data for a single IVF list.
Fields
Filtering for ANN Types
neighbors::filtering::FilterType
Filtering for ANN Types
Values
neighbors::filtering::none_sample_filter::operator
Returns
constexpr __forceinline__ _RAFT_HOST_DEVICE bool
neighbors::filtering::none_sample_filter::get_filter_type
Returns
neighbors::filtering::ivf_to_sample_filter
Filter used to convert the cluster index and sample index of an IVF search into a sample index. This can be used as an intermediate filter.
Fields
neighbors::filtering::ivf_to_sample_filter::operator
If the original filter takes three arguments, then don’t modify the arguments.
If the original filter takes two arguments, then we are using inds_ptr_ to obtain the sample index.
Returns
inline _RAFT_HOST_DEVICE bool
neighbors::filtering::bitmap_filter
Filter an index with a bitmap
Fields
neighbors::filtering::bitmap_filter::operator
Returns
inline _RAFT_HOST_DEVICE bool
neighbors::filtering::bitmap_filter::get_filter_type
Returns
neighbors::filtering::bitset_filter
Filter an index with a bitset
This filter holds a non-owning view of the bitset; it does not allocate or copy the underlying device buffer. The library performs no caching of the bitset across search calls. Allocating and populating the device bitset may be more expensive than a single filtered search, so callers that issue repeated searches against the same filter (e.g. many queries over one index) should build the bitset once and reuse it across those calls rather than rebuild it per search. Reusing the bitset is essential for realizing the full throughput of filtered search.
Fields
neighbors::filtering::bitset_filter::bitset_filter
Parameters
Returns
_RAFT_HOST_DEVICE
neighbors::filtering::bitset_filter::get_filter_type
Returns
neighbors::filtering::bloom_filter
Filter CAGRA candidates with a global cuvs::core::bloom_filter over the index.
Build the filter once on the host with bulk add() over the allowed dataset row ids and pass the owning cuvs::core::bloom_filter to this wrapper. CAGRA internals build/cache the device payload, similar to bitset_filter, and the linked JIT-LTO fragment probes the same filter for every query and candidate with probabilistic membership tests.
Bloom filters have no false negatives: if a row was inserted, contains returns true. False positives are possible, so highly selective predicates may still need a bitset or UDF for exact filtering.
This adapter is non-owning. The referenced cuvs::core::bloom_filter must outlive the adapter and any searches that use it, and must not be moved or mutated concurrently with a search.
Fields
neighbors::filtering::roaring_bitmap_filter
Reusable per-query mapping to immutable exact Roaring allowlists.
Entry q selects view q. CAGRA retains candidate dataset row r when the selected allowlist contains r. Construction copies only already initialized device-reference pointers and empty flags into the filter payload; encoded bytes are neither copied nor parsed. Search therefore performs no Roaring allocation, initialization, synchronization, or preprocessing.
Owners and views can be reused across filters and queries. This filter owns its mapping tables and device payload, but not the referenced owners, which must outlive the filter and all searches using it. Copies are cheap shared handles required by CAGRA query-offset wrappers.
Roaring filters currently support direct cagra::search only. Dynamic batching can combine requests into a different query-row layout, and tiered search applies one filter to partitions with different row domains; both paths reject this filter type.
neighbors::filtering::roaring_bitmap_filter::roaring_bitmap_filter
Construct an invalid handle. It cannot be passed to CAGRA search.
Returns
void
Additional overload: neighbors::filtering::roaring_bitmap_filter::roaring_bitmap_filter
Materialize the query-to-allowlist device pointer table.
dataset_rows(). Query count is inferred from the span length.
Parameters
Returns
explicit
neighbors::filtering::roaring_bitmap_filter::filtering_rate
Conservative maximum rejected fraction among all query allowlists.
CAGRA uses this precomputed value when search_params::filtering_rate is unset. Basing one batch-wide scalar on the sparsest query avoids under-provisioning that query, but a very sparse or empty allowlist can increase the search work performed for every query in the batch. Callers may set search_params::filtering_rate explicitly when another tradeoff is preferable.
Returns
[[nodiscard]] float
neighbors::filtering::roaring_bitmap_filter::size_bytes
Device bytes owned by this mapping, excluding the referenced allowlists.
Returns
[[nodiscard]] std::size_t
neighbors::filtering::roaring_bitmap_filter::set_allowlist
Replace one query’s allowlist pointer outside the search path.
The replacement must have the same dataset_rows(). Copies share the underlying mapping, so the replacement is visible through every copy of this filter. The method copies one pointer and one empty flag to the device and synchronizes res before returning. Do not call it concurrently with a search, and keep the replacement owner alive for all subsequent searches.
Parameters
Returns
void
neighbors::filtering::roaring_bitmap_filter::device_payload
Internal device payload already prepared for the linked CAGRA predicate.
Returns
[[nodiscard]] void*
neighbors::filtering::udf_filter
JIT-LTO user-defined filter predicate.
The source must define a device function named by function_name with signature:
Return true to allow a source vector to appear in the results and false to reject it. UDF dereferences it. CAGRA currently provides source_index_t as uint32_t in the generated JIT fragment.
Fields
ANN MG index build parameters
neighbors::distribution_mode
Values
neighbors::mg_index_params
Fields
ANN MG search parameters
neighbors::replicated_search_mode
Values
neighbors::sharded_merge_mode
Values
neighbors::mg_search_params
Fields