Tiered Index#
2026-09-01
3 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.h>
Tiered Index build parameters#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexParamsCreate (cuvsTieredIndexParams_t *index_params)
Allocate Tiered Index Params and populate with default values.
- Parameters:
index_params – [in] cuvsTieredIndexParams_t to allocate
- Returns:
cuvsError_t
- CUVS_EXPORT cuvsError_t cuvsTieredIndexParamsDestroy (cuvsTieredIndexParams_t index_params)
De-allocate Tiered Index params.
- Parameters:
index_params – [in]
- Returns:
cuvsError_t
-
struct cuvsTieredIndexParams#
- #include <tiered_index.h>
Supplemental parameters to build a TieredIndex.
Public Members
-
cuvsDistanceType metric#
Distance type.
-
cuvsTieredIndexANNAlgo algo#
The type of ANN algorithm we are using
-
int64_t min_ann_rows#
The minimum number of rows necessary in the index to create an ann index
-
bool create_ann_index_on_extend#
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
-
cuvsCagraIndexParams_t cagra_params#
Optional parameters for building a cagra index
-
cuvsIvfFlatIndexParams_t ivf_flat_params#
Optional parameters for building a ivf_flat index
-
cuvsIvfPqIndexParams_t ivf_pq_params#
Optional parameters for building a ivf-pq index
-
cuvsDistanceType metric#
Tiered Index#
-
typedef cuvsTieredIndex *cuvsTieredIndex_t#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexCreate (cuvsTieredIndex_t *index)
Allocate Tiered Index.
- Parameters:
index – [in] cuvsTieredIndex_t to allocate
- Returns:
cuvsError_t
- CUVS_EXPORT cuvsError_t cuvsTieredIndexDestroy (cuvsTieredIndex_t index)
De-allocate Tiered index.
- Parameters:
index – [in] cuvsTieredIndex_t to de-allocate
-
struct cuvsTieredIndex#
- #include <tiered_index.h>
Struct to hold address of cuvs::neighbors::tiered_index::index and its active trained dtype.
Tiered index build#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexBuild (cuvsResources_t res, cuvsTieredIndexParams_t index_params, DLManagedTensor *dataset, cuvsTieredIndex_t index)
Build a TieredIndex index with a
DLManagedTensorwhich has underlyingDLDeviceTypeequal tokDLCUDA,kDLCUDAHost,kDLCUDAManaged, orkDLCPU. Also, acceptable underlying types are:kDLDataType.code == kDLFloatandkDLDataType.bits = 32kDLDataType.code == kDLFloatandkDLDataType.bits = 16
#include <cuvs/core/c_api.h> #include <cuvs/neighbors/tiered_index.h> // Create cuvsResources_t cuvsResources_t res; cuvsError_t res_create_status = cuvsResourcesCreate(&res); // Assume a populated `DLManagedTensor` type here DLManagedTensor dataset; // Create TieredIndex index cuvsTieredIndex_t index; cuvsError_t index_create_status = cuvsTieredIndexCreate(&index); // Create default index params cuvsTieredIndexParams_t index_params; cuvsError_t params_create_status = cuvsTieredIndexParamsCreate(&index_params); // Build the TieredIndex Index cuvsError_t build_status = cuvsTieredIndexBuild(res, index_params, &dataset_tensor, index); // de-allocate `index` and `res` cuvsError_t index_destroy_status = cuvsTieredIndexDestroy(index); cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);
- Parameters:
res – [in] cuvsResources_t opaque C handle
dataset – [in] DLManagedTensor* training dataset
index_params – [in] Index parameters to use when building the index
index – [out] cuvsTieredIndex_t Newly built TieredIndex index
- Returns:
cuvsError_t
Tiered index search#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexSearch (cuvsResources_t res, void *search_params, cuvsTieredIndex_t index, DLManagedTensor *queries, DLManagedTensor *neighbors, DLManagedTensor *distances, cuvsFilter prefilter)
Search a TieredIndex index with a
DLManagedTensor#include <cuvs/core/c_api.h> #include <cuvs/neighbors/tiered_index.h> // Create cuvsResources_t cuvsResources_t res; cuvsError_t res_create_status = cuvsResourcesCreate(&res); // Assume a populated `DLManagedTensor` type here DLManagedTensor dataset; DLManagedTensor queries; DLManagedTensor neighbors; DLManagedTensor bitmap; cuvsFilter prefilter{(uintptr_t)&bitmap, BITMAP}; // Search the `index` built using `cuvsTieredIndexBuild` cuvsError_t search_status = cuvsTieredIndexSearch(res, index, &queries, &neighbors, &distances, prefilter); // de-allocate `res` cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);
- Parameters:
res – [in] cuvsResources_t opaque C handle
search_params – [in] params used to the ANN index, should be one of cuvsCagraSearchParams_t, cuvsIvfFlatSearchParams_t, cuvsIvfPqSearchParams_t depending on the type of the tiered index used
index – [in] cuvsTieredIndex which has been returned by
cuvsTieredIndexBuildqueries – [in] DLManagedTensor* queries dataset to search
neighbors – [out] DLManagedTensor* output
kneighbors for queriesdistances – [out] DLManagedTensor* output
kdistances for queriesprefilter – [in] cuvsFilter input prefilter that can be used to filter queries and neighbors based on the given bitmap.
Tiered index extend#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexExtend (cuvsResources_t res, DLManagedTensor *new_vectors, cuvsTieredIndex_t index)
Extend the index with the new data.
- Parameters:
res – [in] cuvsResources_t opaque C handle
new_vectors – [in] DLManagedTensor* the new vectors to add to the index
index – [inout] Tiered index to be extended
- Returns:
cuvsError_t
Tiered index merge#
- CUVS_EXPORT cuvsError_t cuvsTieredIndexMerge (cuvsResources_t res, cuvsTieredIndexParams_t index_params, cuvsTieredIndex_t *indices, size_t num_indices, cuvsTieredIndex_t output_index)
Merge multiple indices together into a single index.
- Parameters:
res – [in] cuvsResources_t opaque C handle
index_params – [in] Index parameters to use when merging
indices – [in] pointers to indices to merge together
num_indices – [in] the number of indices to merge
output_index – [out] the merged index
- Returns:
cuvsError_t