All-Neighbors#

2026-08-27

2 min read time

Applies to Linux

The all-neighbors method constructs a k-NN graph for all vectors in a dataset. It supports multiple algorithms including brute force, IVF-PQ (approximate), and NN-Descent (approximate) for building local k-NN subgraphs. The API automatically detects whether the dataset is host-resident or device-resident and applies appropriate optimizations.

#include <cuvs/neighbors/all_neighbors.h>

Build parameters#

enum cuvsAllNeighborsAlgo#

Graph build algorithm selection.

Values:

enumerator CUVS_ALL_NEIGHBORS_ALGO_BRUTE_FORCE#

Use Brute Force for local kNN subgraphs.

enumerator CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ#

Use IVF-PQ for local kNN subgraphs (host dataset only)

enumerator CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT#

Use NN-Descent for local kNN subgraphs.

CUVS_EXPORT cuvsError_t cuvsAllNeighborsIndexParamsCreate (cuvsAllNeighborsIndexParams_t *index_params)

Create a default all-neighbors index parameters struct.

Parameters:

index_params – [out] Pointer to allocated index_params struct

Returns:

cuvsError_t

CUVS_EXPORT cuvsError_t cuvsAllNeighborsIndexParamsDestroy (cuvsAllNeighborsIndexParams_t index_params)

Destroy an all-neighbors index parameters struct.

Parameters:

index_params – [in] Index parameters struct to destroy

Returns:

cuvsError_t

struct cuvsAllNeighborsIndexParams#
#include <all_neighbors.h>

Parameters controlling SNMG all-neighbors build.

Public Members

cuvsAllNeighborsAlgo algo#

Local kNN graph build algorithm.

size_t overlap_factor#

Number of clusters each point is assigned to (must be < n_clusters)

size_t n_clusters#

Number of clusters/batches to partition the dataset into (> overlap_factor)

cuvsDistanceType metric#

Distance metric used for graph construction.

cuvsIvfPqIndexParams_t ivf_pq_params#

Parameters for IVF-PQ algorithm (when algo == CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ)

cuvsNNDescentIndexParams_t nn_descent_params#

Parameters for NN-Descent algorithm (when algo == CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT)

Build#

CUVS_EXPORT cuvsError_t cuvsAllNeighborsBuild (cuvsResources_t res, cuvsAllNeighborsIndexParams_t params, DLManagedTensor *dataset, DLManagedTensor *indices, DLManagedTensor *distances, DLManagedTensor *core_distances, float alpha)

Build an all-neighbors k-NN graph automatically detecting host vs device dataset.

The function automatically detects whether the dataset is host-resident or device-resident and calls the appropriate implementation. For host datasets, it partitions data into n_clusters clusters and assigns each row to overlap_factor nearest clusters. For device datasets, n_clusters must be 1 (no batching); overlap_factor is ignored. Outputs always reside in device memory.

Parameters:
  • res – [in] Can be a SNMG multi-GPU resources (cuvsResources_t) or single-GPU resources

  • params – [in] Build parameters (see cuvsAllNeighborsIndexParams)

  • dataset – [in] 2D tensor [num_rows x dim] on host or device (auto-detected)

  • indices – [out] 2D tensor [num_rows x k] on device (int64)

  • distances – [out] Optional 2D tensor [num_rows x k] on device (float32); can be NULL

  • core_distances – [out] Optional 1D tensor [num_rows] on device (float32); can be NULL

  • alpha – [in] Mutual-reachability scaling; used only when core_distances is provided