Tiered Index#

2026-09-01

4 min read time

Applies to Linux

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#

Public Members

int64_t min_ann_rows = 100000#

The minimum number of rows necessary in the index to create an ann index

bool create_ann_index_on_extend = false#

Whether or not to create a new ann index on extend, if the number of rows in the incremental (bfknn) portion is above min_ann_rows

Index#

template<typename UpstreamT>
struct index : public cuvs::neighbors::index#
#include <tiered_index.hpp>

Tiered Index class.

Public Functions

int64_t size(
) const noexcept#

Total length of the index.

int64_t dim(
) const noexcept#

Dimensionality of the data.

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
) -> tiered_index::index<cagra::index<float, uint32_t>>#

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
) -> tiered_index::index<ivf_flat::index<float, int64_t>>#
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
) -> tiered_index::index<ivf_pq::typed_index<float, int64_t>>#

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 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
) -> tiered_index::index<cagra::index<float, uint32_t>>#

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
) -> tiered_index::index<ivf_flat::index<float, int64_t>>#
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
) -> tiered_index::index<ivf_pq::typed_index<float, int64_t>>#