Tiered Index#

2026-09-01

3 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.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

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 DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are:

  1. kDLDataType.code == kDLFloat and kDLDataType.bits = 32

  2. kDLDataType.code == kDLFloat and kDLDataType.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 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