For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
GitHubCUDA-X
    • Home
    • Installation
  • Getting Started
    • Introduction
    • Integrations
    • Use-cases
  • User Guide
    • API Guide
    • Benchmarking Guide
    • Field Guide
    • References
  • Developer Guide
    • Coding Guidelines
    • Contributing
  • API Reference
    • C API Documentation
    • Cpp API Documentation
      • Cluster Agglomerative
      • Cluster Kmeans
      • Cluster Spectral
      • Common Types
      • Distance Distance
      • Distance Grammian
      • Neighbors All Neighbors
      • Neighbors Ball Cover
      • Neighbors Brute Force
      • Neighbors Cagra
      • Neighbors Common
      • Neighbors Dynamic Batching
      • Neighbors Epsilon Neighborhood
      • Neighbors HNSW
      • Neighbors Composite Index
      • Neighbors IVF Flat
      • Neighbors IVF PQ
      • Neighbors IVF SQ
      • Neighbors NN Descent
      • Neighbors Refine
      • Neighbors Scann
      • Neighbors Tiered Index
      • Neighbors Vamana
      • Preprocessing Quantize Binary
      • Preprocessing PCA
      • Preprocessing Quantize PQ
      • Preprocessing Quantize Scalar
      • Preprocessing Spectral Embedding
      • Selection Select K
      • Stats Silhouette Score
      • Stats Trustworthiness Score
      • Util Cutlass Utils
      • Util File Io
    • Python API Documentation
    • Java API Documentation
    • Rust API Documentation
    • Go API Documentation
NVIDIANVIDIA
Developer-friendly docs for your API
Privacy Policy | Your Privacy Choices | Terms of Service | Accessibility | Corporate Policies | Product Security | Contact

Copyright © 2026, NVIDIA Corporation.

LogoLogocuVS
GitHubCUDA-X
On this page
  • Approximate Nearest Neighbors Refinement
  • neighbors::refine
API ReferenceCpp API Documentation

Refine

||View as Markdown|
Previous

Neighbors NN Descent

Next

Neighbors Scann

Source header: cuvs/neighbors/refine.hpp

Approximate Nearest Neighbors Refinement

neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::device_matrix_view<const float, int64_t, raft::row_major> dataset,
3raft::device_matrix_view<const float, int64_t, raft::row_major> queries,
4raft::device_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::device_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::device_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::device_matrix_view<const float, int64_t, raft::row_major>device matrix that stores the dataset [n_rows, dims]
queriesinraft::device_matrix_view<const float, int64_t, raft::row_major>device matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::device_matrix_view<const int64_t, int64_t, raft::row_major>indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::device_matrix_view<int64_t, int64_t, raft::row_major>device matrix that stores the refined indices [n_queries, k]
distancesoutraft::device_matrix_view<float, int64_t, raft::row_major>device matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::device_matrix_view<const float, int64_t, raft::row_major> dataset,
3raft::device_matrix_view<const float, int64_t, raft::row_major> queries,
4raft::device_matrix_view<const uint32_t, int64_t, raft::row_major> neighbor_candidates,
5raft::device_matrix_view<uint32_t, int64_t, raft::row_major> indices,
6raft::device_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::device_matrix_view<const float, int64_t, raft::row_major>device matrix that stores the dataset [n_rows, dims]
queriesinraft::device_matrix_view<const float, int64_t, raft::row_major>device matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::device_matrix_view<const uint32_t, int64_t, raft::row_major>indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::device_matrix_view<uint32_t, int64_t, raft::row_major>device matrix that stores the refined indices [n_queries, k]
distancesoutraft::device_matrix_view<float, int64_t, raft::row_major>device matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::device_matrix_view<const half, int64_t, raft::row_major> dataset,
3raft::device_matrix_view<const half, int64_t, raft::row_major> queries,
4raft::device_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::device_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::device_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::device_matrix_view<const half, int64_t, raft::row_major>device matrix that stores the dataset [n_rows, dims]
queriesinraft::device_matrix_view<const half, int64_t, raft::row_major>device matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::device_matrix_view<const int64_t, int64_t, raft::row_major>indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::device_matrix_view<int64_t, int64_t, raft::row_major>device matrix that stores the refined indices [n_queries, k]
distancesoutraft::device_matrix_view<float, int64_t, raft::row_major>device matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::device_matrix_view<const int8_t, int64_t, raft::row_major> dataset,
3raft::device_matrix_view<const int8_t, int64_t, raft::row_major> queries,
4raft::device_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::device_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::device_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::device_matrix_view<const int8_t, int64_t, raft::row_major>device matrix that stores the dataset [n_rows, dims]
queriesinraft::device_matrix_view<const int8_t, int64_t, raft::row_major>device matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::device_matrix_view<const int64_t, int64_t, raft::row_major>indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::device_matrix_view<int64_t, int64_t, raft::row_major>device matrix that stores the refined indices [n_queries, k]
distancesoutraft::device_matrix_view<float, int64_t, raft::row_major>device matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::device_matrix_view<const uint8_t, int64_t, raft::row_major> dataset,
3raft::device_matrix_view<const uint8_t, int64_t, raft::row_major> queries,
4raft::device_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::device_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::device_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::device_matrix_view<const uint8_t, int64_t, raft::row_major>device matrix that stores the dataset [n_rows, dims]
queriesinraft::device_matrix_view<const uint8_t, int64_t, raft::row_major>device matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::device_matrix_view<const int64_t, int64_t, raft::row_major>indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::device_matrix_view<int64_t, int64_t, raft::row_major>device matrix that stores the refined indices [n_queries, k]
distancesoutraft::device_matrix_view<float, int64_t, raft::row_major>device matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::host_matrix_view<const float, int64_t, raft::row_major> dataset,
3raft::host_matrix_view<const float, int64_t, raft::row_major> queries,
4raft::host_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::host_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::host_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::host_matrix_view<const float, int64_t, raft::row_major>host matrix that stores the dataset [n_rows, dims]
queriesinraft::host_matrix_view<const float, int64_t, raft::row_major>host matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::host_matrix_view<const int64_t, int64_t, raft::row_major>host matrix with indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::host_matrix_view<int64_t, int64_t, raft::row_major>host matrix that stores the refined indices [n_queries, k]
distancesoutraft::host_matrix_view<float, int64_t, raft::row_major>host matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::host_matrix_view<const float, int64_t, raft::row_major> dataset,
3raft::host_matrix_view<const float, int64_t, raft::row_major> queries,
4raft::host_matrix_view<const uint32_t, int64_t, raft::row_major> neighbor_candidates,
5raft::host_matrix_view<uint32_t, int64_t, raft::row_major> indices,
6raft::host_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::host_matrix_view<const float, int64_t, raft::row_major>host matrix that stores the dataset [n_rows, dims]
queriesinraft::host_matrix_view<const float, int64_t, raft::row_major>host matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::host_matrix_view<const uint32_t, int64_t, raft::row_major>host matrix with indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::host_matrix_view<uint32_t, int64_t, raft::row_major>host matrix that stores the refined indices [n_queries, k]
distancesoutraft::host_matrix_view<float, int64_t, raft::row_major>host matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::host_matrix_view<const half, int64_t, raft::row_major> dataset,
3raft::host_matrix_view<const half, int64_t, raft::row_major> queries,
4raft::host_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::host_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::host_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::host_matrix_view<const half, int64_t, raft::row_major>host matrix that stores the dataset [n_rows, dims]
queriesinraft::host_matrix_view<const half, int64_t, raft::row_major>host matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::host_matrix_view<const int64_t, int64_t, raft::row_major>host matrix with indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::host_matrix_view<int64_t, int64_t, raft::row_major>host matrix that stores the refined indices [n_queries, k]
distancesoutraft::host_matrix_view<float, int64_t, raft::row_major>host matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::host_matrix_view<const int8_t, int64_t, raft::row_major> dataset,
3raft::host_matrix_view<const int8_t, int64_t, raft::row_major> queries,
4raft::host_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::host_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::host_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::host_matrix_view<const int8_t, int64_t, raft::row_major>host matrix that stores the dataset [n_rows, dims]
queriesinraft::host_matrix_view<const int8_t, int64_t, raft::row_major>host matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::host_matrix_view<const int64_t, int64_t, raft::row_major>host matrix with indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::host_matrix_view<int64_t, int64_t, raft::row_major>host matrix that stores the refined indices [n_queries, k]
distancesoutraft::host_matrix_view<float, int64_t, raft::row_major>host matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void

Additional overload: neighbors::refine

Refine nearest neighbor search.

1void refine(raft::resources const& handle,
2raft::host_matrix_view<const uint8_t, int64_t, raft::row_major> dataset,
3raft::host_matrix_view<const uint8_t, int64_t, raft::row_major> queries,
4raft::host_matrix_view<const int64_t, int64_t, raft::row_major> neighbor_candidates,
5raft::host_matrix_view<int64_t, int64_t, raft::row_major> indices,
6raft::host_matrix_view<float, int64_t, raft::row_major> distances,
7cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);

Refinement is an operation that follows an approximate NN search. The approximate search has already selected n_candidates neighbor candidates for each query. We narrow it down to k neighbors. For each query, we calculate the exact distance between the query and its n_candidates neighbor candidate, and select the k nearest ones.

The k nearest neighbors and distances are returned.

Example usage

Parameters

NameDirectionTypeDescription
handleinraft::resources const&the raft handle
datasetinraft::host_matrix_view<const uint8_t, int64_t, raft::row_major>host matrix that stores the dataset [n_rows, dims]
queriesinraft::host_matrix_view<const uint8_t, int64_t, raft::row_major>host matrix of the queries [n_queris, dims]
neighbor_candidatesinraft::host_matrix_view<const int64_t, int64_t, raft::row_major>host matrix with indices of candidate vectors [n_queries, n_candidates], where n_candidates >= k
indicesoutraft::host_matrix_view<int64_t, int64_t, raft::row_major>host matrix that stores the refined indices [n_queries, k]
distancesoutraft::host_matrix_view<float, int64_t, raft::row_major>host matrix that stores the refined distances [n_queries, k]
metricincuvs::distance::DistanceTypedistance metric to use. Euclidean (L2) is used by default
Default: cuvs::distance::DistanceType::L2Unexpanded.

Returns

void