Tiered Index#
2026-09-01
4 min read time
The Tiered Index combines an exact brute-force index for incrementally added vectors with an approximate nearest neighbors index (CAGRA, IVF-Flat, or IVF-PQ) for the bulk of the dataset, automatically promoting data from the exact tier into the ANN tier as it grows.
#include <cuvs/neighbors/tiered_index.hpp>
namespace cuvs::neighbors::tiered_index
Index build parameters#
-
template<typename upstream_index_params_type>
struct index_params : public upstream_index_params_type#
Index#
-
template<typename UpstreamT>
struct index : public cuvs::neighbors::index# - #include <tiered_index.hpp>
Tiered Index class.
Index build#
- auto build(
- raft::resources const &res,
- const index_params<cagra::index_params> &index_params,
- raft::device_matrix_view<const float, int64_t, raft::row_major> dataset
Build the index from the dataset for efficient search.
Usage example:
using namespace cuvs::neighbors; // use default index parameters tiered_index::index_params<cagra::index_params> build_params; // create and fill the index from a [N, D] dataset auto index = tiered_index::build(handle, build_params, dataset);
- Parameters:
res – [in]
index_params – configure the index building
dataset – [in] a device matrix view to a row-major matrix [n_rows, dim]
- Returns:
the constructed tiered index
- auto build(
- raft::resources const &res,
- const index_params<ivf_flat::index_params> &index_params,
- raft::device_matrix_view<const float, int64_t, raft::row_major> dataset
- auto build(
- raft::resources const &res,
- const index_params<ivf_pq::index_params> &index_params,
- raft::device_matrix_view<const float, int64_t, raft::row_major> dataset
Index extend#
- void extend(
- raft::resources const &res,
- raft::device_matrix_view<const float, int64_t, raft::row_major> new_vectors,
- tiered_index::index<cagra::index<float, uint32_t>> *idx
Extend the index with the new data.
Usage example:
using namespace cuvs::neighbors; tiered_index::index_params<cagra::index_params> index_params; // train the index from a [N, D] dataset auto index_empty = tiered_index::build(res, index_params, dataset); // add new data to the index tiered_index::extend(res, new_vectors, &index_empty);
- Parameters:
res – [in]
new_vectors – [in] a device matrix view to a row-major matrix [n_rows, idx.dim()]
idx – [inout]
- void extend(
- raft::resources const &res,
- raft::device_matrix_view<const float, int64_t, raft::row_major> new_vectors,
- tiered_index::index<ivf_flat::index<float, int64_t>> *idx
- void extend(
- raft::resources const &res,
- raft::device_matrix_view<const float, int64_t, raft::row_major> new_vectors,
- tiered_index::index<ivf_pq::typed_index<float, int64_t>> *idx
Index compact#
- void compact(
- raft::resources const &res,
- tiered_index::index<cagra::index<float, uint32_t>> *idx
Compact the index.
This function takes any data that has been added incrementally, and ensures that it been added to the ANN index.
- Parameters:
res – [in]
idx – [inout]
- void compact(
- raft::resources const &res,
- tiered_index::index<ivf_flat::index<float, int64_t>> *idx
- void compact(
- raft::resources const &res,
- tiered_index::index<ivf_pq::typed_index<float, int64_t>> *idx
Index search#
- void search(
- raft::resources const &res,
- const cagra::search_params &search_params,
- const tiered_index::index<cagra::index<float, uint32_t>> &index,
- raft::device_matrix_view<const float, int64_t, raft::row_major> queries,
- raft::device_matrix_view<int64_t, int64_t, raft::row_major> neighbors,
- raft::device_matrix_view<float, int64_t, raft::row_major> distances,
- const cuvs::neighbors::filtering::base_filter &sample_filter = cuvs::neighbors::filtering::none_sample_filter{}
Search the tiered_index.
- Parameters:
res – [in]
search_params – [in] configure the search
index – [in] tiered-index constructed index
queries – [in] a device matrix view to a row-major matrix [n_queries, index->dim()]
neighbors – [out] a device matrix view to the indices of the neighbors in the source dataset [n_queries, k]
distances – [out] a device matrix view to the distances to the selected neighbors [n_queries, k]
sample_filter – [in] an optional device filter function object that greenlights samples for a given query. (none_sample_filter for no filtering)
- void search(
- raft::resources const &res,
- const ivf_flat::search_params &search_params,
- const tiered_index::index<ivf_flat::index<float, int64_t>> &index,
- raft::device_matrix_view<const float, int64_t, raft::row_major> queries,
- raft::device_matrix_view<int64_t, int64_t, raft::row_major> neighbors,
- raft::device_matrix_view<float, int64_t, raft::row_major> distances,
- const cuvs::neighbors::filtering::base_filter &sample_filter = cuvs::neighbors::filtering::none_sample_filter{}
- void search(
- raft::resources const &res,
- const ivf_pq::search_params &search_params,
- const tiered_index::index<ivf_pq::typed_index<float, int64_t>> &index,
- raft::device_matrix_view<const float, int64_t, raft::row_major> queries,
- raft::device_matrix_view<int64_t, int64_t, raft::row_major> neighbors,
- raft::device_matrix_view<float, int64_t, raft::row_major> distances,
- const cuvs::neighbors::filtering::base_filter &sample_filter = cuvs::neighbors::filtering::none_sample_filter{}
Index merge#
- auto merge(
- raft::resources const &res,
- const index_params<cagra::index_params> &index_params,
- const std::vector<tiered_index::index<cagra::index<float, uint32_t>>*> &indices
Merge multiple tiered indices into a single index.
This function merges multiple tiered indices into one, combining both the datasets and graph structures.
- Parameters:
res – [in]
index_params – configure the index building
indices – [in] A vector of pointers to the indices to merge. All indices should be of the same type, and have datasets with the same dimensionality
- Returns:
A new tiered index containing the merged indices
- auto merge(
- raft::resources const &res,
- const index_params<ivf_flat::index_params> &index_params,
- const std::vector<tiered_index::index<ivf_flat::index<float, int64_t>>*> &indices
- auto merge(
- raft::resources const &res,
- const index_params<ivf_pq::index_params> &index_params,
- const std::vector<tiered_index::index<ivf_pq::typed_index<float, int64_t>>*> &indices