Tiered Index#
2026-09-01
4 min read time
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.IndexParamsdataset : 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 search#
- cuvs.neighbors.tiered_index.search(*args, resources=None, **kwargs)#
search(search_params, Index index, queries, k, neighbors=None, distances=None, resources=None, filter=None)
Find the k nearest neighbors for each query.
Parameters#
search_params : SearchParams for the upstream ANN index index : py:class:cuvs.neighbors.tiered_index.Index
Trained Tiered index.
- queriesCUDA array interface compliant matrix shape (n_samples, dim)
Supported dtype [float32]
- kint
The number of neighbors.
- neighborsOptional CUDA array interface compliant matrix shape
(n_queries, k), dtype int64_t. If supplied, neighbor indices will be written here in-place. (default None)
- distancesOptional CUDA array interface compliant matrix shape
(n_queries, k) If supplied, the distances to the neighbors will be written here in-place. (default None)
- filter: Optional cuvs.neighbors.cuvsFilter can be used to filter
neighbors based on a given bitset. (default None)
- 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.
Examples#
>>> import cupy as cp >>> from cuvs.neighbors import cagra, tiered_index >>> n_samples = 50000 >>> n_features = 50 >>> n_queries = 1000 >>> dataset = cp.random.random_sample((n_samples, n_features), ... dtype=cp.float32) >>> # Build the index >>> index = tiered_index.build(tiered_index.IndexParams(algo="cagra"), ... dataset) >>> >>> # Search using the built index >>> queries = cp.random.random_sample((n_queries, n_features), ... dtype=cp.float32) >>> k = 10 >>> search_params = cagra.SearchParams() >>> >>> distances, neighbors = tiered_index.search(search_params, index, ... queries, k)
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)