Neighbors Tiered Index

Source header: cuvs/neighbors/tiered_index.h

Types

cuvsTieredIndexANNAlgo

Enum to hold which ANN algorithm is being used in the tiered index

1 typedef enum {
2   CUVS_TIERED_INDEX_ALGO_CAGRA = 0,
3   CUVS_TIERED_INDEX_ALGO_IVF_FLAT = 1,
4   CUVS_TIERED_INDEX_ALGO_IVF_PQ = 2
5 } cuvsTieredIndexANNAlgo;

Values

Name	Value
`CUVS_TIERED_INDEX_ALGO_CAGRA`	`0`
`CUVS_TIERED_INDEX_ALGO_IVF_FLAT`	`1`
`CUVS_TIERED_INDEX_ALGO_IVF_PQ`	`2`

Tiered Index

cuvsTieredIndex

Struct to hold address of cuvs::neighbors::tiered_index::index and its active trained dtype

1 typedef struct {
2   uintptr_t addr;
3   DLDataType dtype;
4   cuvsTieredIndexANNAlgo algo;
5 } cuvsTieredIndex;

Fields

Name	Type	Description
`addr`	`uintptr_t`
`dtype`	`DLDataType`
`algo`	`cuvsTieredIndexANNAlgo`

cuvsTieredIndexCreate

Allocate Tiered Index

1 cuvsError_t cuvsTieredIndexCreate(cuvsTieredIndex_t* index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsTieredIndex_t*`	cuvsTieredIndex_t to allocate

Returns

cuvsError_t

cuvsTieredIndexDestroy

De-allocate Tiered index

1 cuvsError_t cuvsTieredIndexDestroy(cuvsTieredIndex_t index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsTieredIndex_t`	cuvsTieredIndex_t to de-allocate

Returns

cuvsError_t

Tiered Index build parameters

cuvsTieredIndexParams

Supplemental parameters to build a TieredIndex

1 struct cuvsTieredIndexParams {
2   cuvsDistanceType metric;
3   cuvsTieredIndexANNAlgo algo;
4   int64_t min_ann_rows;
5   bool create_ann_index_on_extend;
6   cuvsCagraIndexParams_t cagra_params;
7   cuvsIvfFlatIndexParams_t ivf_flat_params;
8   cuvsIvfPqIndexParams_t ivf_pq_params;
9 };

Fields

Name	Type	Description
`metric`	`cuvsDistanceType`	Distance type.
`algo`	`cuvsTieredIndexANNAlgo`	The type of ANN algorithm we are using
`min_ann_rows`	`int64_t`	The minimum number of rows necessary in the index to create an ann index
`create_ann_index_on_extend`	`bool`	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
`cagra_params`	`cuvsCagraIndexParams_t`	Optional parameters for building a cagra index
`ivf_flat_params`	`cuvsIvfFlatIndexParams_t`	Optional parameters for building a ivf_flat index
`ivf_pq_params`	`cuvsIvfPqIndexParams_t`	Optional parameters for building a ivf-pq index

cuvsTieredIndexParamsCreate

Allocate Tiered Index Params and populate with default values

1 cuvsError_t cuvsTieredIndexParamsCreate(cuvsTieredIndexParams_t* index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsTieredIndexParams_t*`	cuvsTieredIndexParams_t to allocate

Returns

cuvsError_t

cuvsTieredIndexParamsDestroy

De-allocate Tiered Index params

1 cuvsError_t cuvsTieredIndexParamsDestroy(cuvsTieredIndexParams_t index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsTieredIndexParams_t`

Returns

cuvsError_t

Tiered index build

cuvsTieredIndexBuild

Build a TieredIndex index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are:

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

1 cuvsError_t cuvsTieredIndexBuild(cuvsResources_t res,
2 cuvsTieredIndexParams_t index_params,
3 DLManagedTensor* dataset,
4 cuvsTieredIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`index_params`	in	`cuvsTieredIndexParams_t`	Index parameters to use when building the index
`dataset`	in	`DLManagedTensor*`	DLManagedTensor* training dataset
`index`	out	`cuvsTieredIndex_t`	cuvsTieredIndex_t Newly built TieredIndex index

Returns

cuvsError_t

Tiered index search

cuvsTieredIndexSearch

Search a TieredIndex index with a DLManagedTensor

1 cuvsError_t cuvsTieredIndexSearch(cuvsResources_t res,
2 void* search_params,
3 cuvsTieredIndex_t index,
4 DLManagedTensor* queries,
5 DLManagedTensor* neighbors,
6 DLManagedTensor* distances,
7 cuvsFilter prefilter);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`search_params`	in	`void*`	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_t`	cuvsTieredIndex which has been returned by `cuvsTieredIndexBuild`
`queries`	in	`DLManagedTensor*`	DLManagedTensor* queries dataset to search
`neighbors`	out	`DLManagedTensor*`	DLManagedTensor* output `k` neighbors for queries
`distances`	out	`DLManagedTensor*`	DLManagedTensor* output `k` distances for queries
`prefilter`	in	`cuvsFilter`	cuvsFilter input prefilter that can be used to filter queries and neighbors based on the given bitmap.

Returns

cuvsError_t

Tiered index extend

cuvsTieredIndexExtend

Extend the index with the new data.

1 cuvsError_t cuvsTieredIndexExtend(cuvsResources_t res,
2 DLManagedTensor* new_vectors,
3 cuvsTieredIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`new_vectors`	in	`DLManagedTensor*`	DLManagedTensor* the new vectors to add to the index
`index`	inout	`cuvsTieredIndex_t`	Tiered index to be extended

Returns

cuvsError_t

Tiered index merge

cuvsTieredIndexMerge

Merge multiple indices together into a single index

1 cuvsError_t cuvsTieredIndexMerge(cuvsResources_t res,
2 cuvsTieredIndexParams_t index_params,
3 cuvsTieredIndex_t* indices,
4 size_t num_indices,
5 cuvsTieredIndex_t output_index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`index_params`	in	`cuvsTieredIndexParams_t`	Index parameters to use when merging
`indices`	in	`cuvsTieredIndex_t*`	pointers to indices to merge together
`num_indices`	in	`size_t`	the number of indices to merge
`output_index`	out	`cuvsTieredIndex_t`	the merged index

Returns

cuvsError_t