ScaNN#

2026-09-01

5 min read time

Applies to Linux

ScaNN (Scalable Nearest Neighbors) is an ANN algorithm that combines partitioning with anisotropic vector quantization to provide fast, accurate nearest neighbor search.

#include <cuvs/neighbors/scann.hpp>

namespace cuvs::neighbors::scann

Index build parameters#

struct index_params : public cuvs::neighbors::index_params#
#include <scann.hpp>

ANN parameters used by ScaNN to build index.

Public Members

uint32_t n_leaves = 1000#

the number of leaves in the tree

int64_t kmeans_n_rows_train = 100000#

the number of rows for training the tree structures

uint32_t kmeans_n_iters = 24#

the max number of iterations for training the tree structure

float partitioning_eta = 1#

the value of eta for AVQ adjustment during partitioning

float soar_lambda = 1#

the value of lambda for SOAR spilling

uint32_t pq_dim = 8#

the dimension of pq subspaces (must divide dataset dimension)

uint32_t pq_bits = 8#

the number of bits for pq codes (must be 4 or 8, for 16 and 256 codes respectively)

int64_t pq_n_rows_train = 100000#

the number of rows for PQ training (internally capped to 100k)

uint32_t pq_train_iters = 10#

the max number of iterations for PQ training

bool reordering_bf16 = false#

whether to apply bf16 quantization of dataset vectors

float reordering_noise_shaping_threshold = NAN#

Threshold T for computing AVQ eta = (dim - 1) ( T^2 / || x ||^2) / ( 1 - T^2 / || x ||^2)

When quantizing a vector x to x_q, AVQ minimizes the loss function L(x, x_q) = eta * || r_para ||^2 + || r_perp ||^2, where r = x - x_q, r_para = <r, x> * x / || x ||^2, r_perp = r - r_para

Compared to L2 loss, This produces an x_q which better approximates the dot product of a query vector with x

If the threshold is NAN, AVQ is not performed during bfloat16 quant

Index#

template<typename T, typename IdxT>
struct index : public cuvs::neighbors::index#
#include <scann.hpp>

ScaNN index.

The index stores the dataset and the ScaNN graph in device memory.

Template Parameters:
  • T – data element type

  • IdxT – type of the vector indices (represent dataset.extent(0))

Public Functions

inline constexpr auto metric(
) const noexcept -> cuvs::distance::DistanceType#

Distance metric used for clustering.

IdxT size(
) const noexcept#

Total length of the index (number of vectors).

inline constexpr auto dim(
) const noexcept -> uint32_t#

Dimensionality of the data.

inline index(
raft::resources const &res,
cuvs::distance::DistanceType metric,
uint32_t n_leaves,
uint32_t pq_bits,
uint32_t pq_dim,
IdxT n_rows,
IdxT dim,
uint32_t pq_clusters,
uint32_t pq_num_subspaces,
bool reordering_bf16
)#

Construct an empty index. It will need to be trained and populated with build

Index build#

uint32_t n_leaves = 1000#

the number of leaves in the tree

int64_t kmeans_n_rows_train = 100000#

the number of rows for training the tree structures

uint32_t kmeans_n_iters = 24#

the max number of iterations for training the tree structure

float partitioning_eta = 1#

the value of eta for AVQ adjustment during partitioning

float soar_lambda = 1#

the value of lambda for SOAR spilling

uint32_t pq_dim = 8#

the dimension of pq subspaces (must divide dataset dimension)

uint32_t pq_bits = 8#

the number of bits for pq codes (must be 4 or 8, for 16 and 256 codes respectively)

int64_t pq_n_rows_train = 100000#

the number of rows for PQ training (internally capped to 100k)

uint32_t pq_train_iters = 10#

the max number of iterations for PQ training

bool reordering_bf16 = false#

whether to apply bf16 quantization of dataset vectors

float reordering_noise_shaping_threshold = NAN#

Threshold T for computing AVQ eta = (dim - 1) ( T^2 / || x ||^2) / ( 1 - T^2 / || x ||^2)

When quantizing a vector x to x_q, AVQ minimizes the loss function L(x, x_q) = eta * || r_para ||^2 + || r_perp ||^2, where r = x - x_q, r_para = <r, x> * x / || x ||^2, r_perp = r - r_para

Compared to L2 loss, This produces an x_q which better approximates the dot product of a query vector with x

If the threshold is NAN, AVQ is not performed during bfloat16 quant

inline constexpr auto metric(
) const noexcept -> cuvs::distance::DistanceType#

Distance metric used for clustering.

IdxT size(
) const noexcept#

Total length of the index (number of vectors).

inline constexpr auto dim(
) const noexcept -> uint32_t#

Dimensionality of the data.

index(
const index&
) = delete#
index(
index&&
) = default#
auto operator=(
const index&
) -> index& = delete#
auto operator=(
index&&
) -> index& = default#
~index(
) = default#
inline index(
raft::resources const &res,
cuvs::distance::DistanceType metric,
uint32_t n_leaves,
uint32_t pq_bits,
uint32_t pq_dim,
IdxT n_rows,
IdxT dim,
uint32_t pq_clusters,
uint32_t pq_num_subspaces,
bool reordering_bf16
)#

Construct an empty index. It will need to be trained and populated with build

inline index(
raft::resources const &res,
const index_params &params,
IdxT n_rows,
IdxT dim
)#
inline raft::device_matrix_view<float, IdxT> centers(
) noexcept#
inline raft::device_matrix_view<const float, IdxT> centers(
) const noexcept#
inline raft::device_vector_view<uint32_t, IdxT> labels(
) noexcept#
inline raft::device_vector_view<const uint32_t, IdxT> labels(
) const noexcept#
inline raft::device_vector_view<uint32_t, IdxT> soar_labels(
) noexcept#
inline raft::device_vector_view<const uint32_t, IdxT> soar_labels(
) const noexcept#
inline uint32_t n_rows(
) const noexcept#
inline uint32_t n_leaves(
) const noexcept
inline uint32_t pq_dim(
) const noexcept
inline raft::device_matrix_view<const float, uint32_t, raft::row_major> pq_codebook(
) const noexcept#
inline raft::device_matrix_view<float, uint32_t, raft::row_major> pq_codebook(
) noexcept#
inline raft::host_matrix_view<const uint8_t, IdxT, raft::row_major> quantized_residuals(
) const noexcept#
inline raft::host_matrix_view<uint8_t, IdxT, raft::row_major> quantized_residuals(
) noexcept#
inline raft::host_matrix_view<const uint8_t, IdxT, raft::row_major> quantized_soar_residuals(
) const noexcept#
inline raft::host_matrix_view<uint8_t, IdxT, raft::row_major> quantized_soar_residuals(
) noexcept#
inline raft::host_matrix_view<int16_t, IdxT, raft::row_major> bf16_dataset(
) noexcept#
inline raft::host_matrix_view<const int16_t, IdxT, raft::row_major> bf16_dataset(
) const noexcept#
auto build(
raft::resources const &handle,
const cuvs::neighbors::experimental::scann::index_params &params,
raft::device_matrix_view<const float, int64_t, raft::row_major> dataset
) -> cuvs::neighbors::experimental::scann::index<float, int64_t>#

Build the index from the dataset for efficient search.

auto build(
raft::resources const &handle,
const cuvs::neighbors::experimental::scann::index_params &params,
raft::host_matrix_view<const float, int64_t, raft::row_major> dataset
) -> cuvs::neighbors::experimental::scann::index<float, int64_t>#

Index serialize#

void serialize(
raft::resources const &handle,
const std::string &file_prefix,
const cuvs::neighbors::experimental::scann::index<float, int64_t> &index
)#

Save the index to files in a directory.

This serializes the index into a list of files for integration into OSS ScaNN for use with search

NOTE: the implementation of ScaNN index build is EXPERIMENTAL and currently not subject to comprehensive, automated testing. Accuracy and performance are not guaranteed, and could diverge without warning.