> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/cuvs/llms.txt.
> For full documentation content, see https://docs.nvidia.com/cuvs/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/cuvs/_mcp/server.
# Common
_Source header: `cuvs/neighbors/common.hpp`_
## Approximate Nearest Neighbors Types
### neighbors::index
The base for approximate KNN index structures.
```cpp
struct index { ... };
```
### neighbors::index_params
The base for KNN index parameters.
```cpp
struct index_params { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `metric` | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | Distance type. |
| `metric_arg` | `float` | The argument used by some distance metrics. |
### 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.
```cpp
enum class MergeStrategy { ... };
```
**Values**
| Name | Value |
| --- | --- |
| `MERGE_STRATEGY_PHYSICAL` | `0` |
| `MERGE_STRATEGY_LOGICAL` | `1` |
## Types
### neighbors::dataset
Two-dimensional dataset; maybe owning, maybe compressed, maybe strided.
```cpp
template
struct dataset { ... };
```
### neighbors::vpq_dataset
VPQ compressed dataset.
The dataset is compressed using two level quantization
1. Vector Quantization
2. Product Quantization of residuals
```cpp
template
struct vpq_dataset : public dataset { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `vq_code_book` | `raft::device_matrix` | Vector Quantization codebook - "coarse cluster centers". |
| `pq_code_book` | `raft::device_matrix` | Product Quantization codebook - "fine cluster centers". |
| `data` | `raft::device_matrix` | Compressed dataset. |
### 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/rapidsai/cuvs/issues/1726)
```cpp
template
struct list_base { ... };
```
### neighbors::ivf::list
The data for a single IVF list.
```cpp
template typename SpecT,
typename SizeT,
typename... SpecExtraArgs>
struct list : public list_base::value_type,
typename SpecT::index_type,
SizeT> { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `data` | [`raft::device_mdarray`](/api-reference/cpp-api-neighbors-ivf-pq#list-extents) | Possibly encoded data; it's layout is defined by `SpecT`. |
| `indices` | `raft::device_mdarray, raft::row_major>` | Source indices. |
| `size` | `std::atomic` | The actual size of the content. |
## Filtering for ANN Types
### neighbors::filtering::FilterType
Filtering for ANN Types
```cpp
enum class FilterType { ... };
```
**Values**
| Name | Value |
| --- | --- |
| `None` | `` |
| `Bitmap` | `` |
| `Bitset` | `` |
### neighbors::filtering::none_sample_filter::operator
```cpp
constexpr __forceinline__ _RAFT_HOST_DEVICE bool operator()(
// query index
const uint32_t query_ix,
// the current inverted list index
const uint32_t cluster_ix,
// the index of the current sample inside the current inverted list
const uint32_t sample_ix) const;
```
**Returns**
`constexpr __forceinline__ _RAFT_HOST_DEVICE bool`
### neighbors::filtering::none_sample_filter::get_filter_type
```cpp
FilterType get_filter_type() const override;
```
**Returns**
[`FilterType`](/api-reference/cpp-api-neighbors-common#neighbors-filtering-filtertype)
### 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.
```cpp
template
struct ivf_to_sample_filter : public base_filter { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `inds_ptrs_` | `const index_t* const*` | |
| `next_filter_` | `const filter_t` | |
### neighbors::filtering::ivf_to_sample_filter::operator
If the original filter takes three arguments, then don't modify the arguments.
```cpp
inline _RAFT_HOST_DEVICE bool operator()(
// query index
const uint32_t query_ix,
// the current inverted list index
const uint32_t cluster_ix,
// the index of the current sample inside the current inverted list
const uint32_t sample_ix) const;
```
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
```cpp
template
struct bitmap_filter : public base_filter { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `bitmap_view_` | `const view_t` | |
### neighbors::filtering::bitmap_filter::operator
```cpp
inline _RAFT_HOST_DEVICE bool operator()(
// query index
const uint32_t query_ix,
// the index of the current sample
const uint32_t sample_ix) const;
```
**Returns**
`inline _RAFT_HOST_DEVICE bool`
### neighbors::filtering::bitmap_filter::get_filter_type
```cpp
FilterType get_filter_type() const override;
```
**Returns**
[`FilterType`](/api-reference/cpp-api-neighbors-common#neighbors-filtering-filtertype)
### neighbors::filtering::bitset_filter
Filter an index with a bitset
```cpp
template
struct bitset_filter : public base_filter { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `bitset_view_` | `const view_t` | |
### neighbors::filtering::bitset_filter::bitset_filter
```cpp
_RAFT_HOST_DEVICE bitset_filter(const view_t bitset_for_filtering);
```
**Parameters**
| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `bitset_for_filtering` | | `const view_t` | |
**Returns**
`_RAFT_HOST_DEVICE`
### neighbors::filtering::bitset_filter::get_filter_type
```cpp
FilterType get_filter_type() const override;
```
**Returns**
[`FilterType`](/api-reference/cpp-api-neighbors-common#neighbors-filtering-filtertype)
## ANN MG index build parameters
### neighbors::distribution_mode
```cpp
enum distribution_mode { ... };
```
### neighbors::mg_index_params
```cpp
template
struct mg_index_params : public Upstream { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `mode` | [`cuvs::neighbors::distribution_mode`](/api-reference/cpp-api-neighbors-common#neighbors-distribution-mode) | Distribution mode |
## ANN MG search parameters
### neighbors::replicated_search_mode
```cpp
enum replicated_search_mode { ... };
```
**Values**
| Name | Value |
| --- | --- |
| `LOAD_BALANCER` | `` |
| `ROUND_ROBIN` | `` |
### neighbors::sharded_merge_mode
```cpp
enum sharded_merge_mode { ... };
```
**Values**
| Name | Value |
| --- | --- |
| `MERGE_ON_ROOT_RANK` | `` |
| `TREE_MERGE` | `` |
### neighbors::mg_search_params
```cpp
template
struct mg_search_params : public Upstream { ... };
```
**Fields**
| Name | Type | Description |
| --- | --- | --- |
| `search_mode` | [`cuvs::neighbors::replicated_search_mode`](/api-reference/cpp-api-neighbors-common#neighbors-replicated-search-mode) | Replicated search mode |
| `merge_mode` | [`cuvs::neighbors::sharded_merge_mode`](/api-reference/cpp-api-neighbors-common#neighbors-sharded-merge-mode) | Sharded merge mode |
| `n_rows_per_batch` | `int64_t` | Number of rows per batch |