Tiered Index#

2026-09-01

4 min read time

Applies to Linux

Index build parameters#

class cuvs.neighbors.tiered_index.IndexParams#

IndexParams(metric=’sqeuclidean’, *, algo=’cagra’, upstream_params=None, min_ann_rows=None, create_ann_index_on_extend=None)

Parameters to build index for Tiered Index nearest neighbor search

Parameters#

metricstr, default = “sqeuclidean”

String denoting the metric type. Valid values for metric: [“sqeuclidean”, “inner_product”, “euclidean”, “cosine”], where

  • sqeuclidean is the euclidean distance without the square root operation, i.e.: distance(a,b) = sum_i (a_i - b_i)^2,

  • euclidean is the euclidean distance

  • inner product distance is defined as distance(a, b) = sum_i a_i * b_i.

  • cosine distance is defined as distance(a, b) = 1 - sum_i a_i * b_i / ( ||a||_2 * ||b||_2).

algostr, default = “cagra”

The algorithm to use for the ANN portion of the tiered index

upstream_paramsobject, optional

The IndexParams for the upstream ANN object to use (ie the Cagra IndexParams for cagra etc)

min_ann_rowsint

The minimum number of rows necessary to create an ann index

create_ann_index_on_extendbool

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#

class cuvs.neighbors.tiered_index.Index#

Tiered Index object.

Index build#

cuvs.neighbors.tiered_index.build(*args, resources=None, **kwargs)#

build(IndexParams index_params, dataset, resources=None)

Build the Tiered index from the dataset for efficient search.

Parameters#

index_params : cuvs.neighbors.tiered_index.IndexParams dataset : CUDA array interface compliant matrix shape (n_samples, dim)

Supported dtype [float32]

resourcesOptional cuVS Resource handle for reusing CUDA resources.

If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Returns#

index: py:class:cuvs.neighbors.tiered_index.Index

Examples#

>>> import cupy as cp
>>> from cuvs.neighbors import cagra, tiered_index
>>> n_samples = 50000
>>> n_features = 50
>>> n_queries = 1000
>>> k = 10
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> build_params = tiered_index.IndexParams(metric="sqeuclidean",
...                                         algo="cagra")
>>> index = tiered_index.build(build_params, dataset)
>>> distances, neighbors = tiered_index.search(cagra.SearchParams(),
...                                            index, dataset, k)
>>> distances = cp.asarray(distances)
>>> neighbors = cp.asarray(neighbors)

Index extend#

cuvs.neighbors.tiered_index.extend(*args, resources=None, **kwargs)#

extend(Index index, new_vectors, resources=None)

Extend an existing index with new vectors.

The input array can be either CUDA array interface compliant matrix or array interface compliant matrix in host memory.

Parameters#

indextiered_index.Index

Trained tiered_index object.

new_vectorsarray interface compliant matrix shape (n_samples, dim)

Supported dtype [float32]

resourcesOptional cuVS Resource handle for reusing CUDA resources.

If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Returns#

index: py:class:cuvs.neighbors.tiered_index.Index

Examples#

>>> import cupy as cp
>>> from cuvs.neighbors import tiered_index
>>> n_samples = 50000
>>> n_features = 50
>>> n_queries = 1000
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> index = tiered_index.build(tiered_index.IndexParams(), dataset)
>>> n_rows = 100
>>> more_data = cp.random.random_sample((n_rows, n_features),
...                                     dtype=cp.float32)
>>> index = tiered_index.extend(index, more_data)