IVF-SQ#

2026-09-01

5 min read time

Applies to Linux

The IVF-SQ method is an ANN algorithm. Like IVF-Flat, IVF-SQ splits the points into a number of clusters (also specified by a parameter called n_lists) and searches the closest clusters to compute the nearest neighbors (also specified by a parameter called n_probes), but it shrinks the sizes of the vectors using scalar quantization.

#include <cuvs/neighbors/ivf_sq.h>

Index build parameters#

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexParamsCreate (cuvsIvfSqIndexParams_t *index_params)

Allocate IVF-SQ Index params, and populate with default values.

Parameters:

index_params – [in] cuvsIvfSqIndexParams_t to allocate

Returns:

cuvsError_t

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexParamsDestroy (cuvsIvfSqIndexParams_t index_params)

De-allocate IVF-SQ Index params.

Parameters:

index_params – [in]

Returns:

cuvsError_t

struct cuvsIvfSqIndexParams#
#include <ivf_sq.h>

Supplemental parameters to build IVF-SQ Index.

Public Members

cuvsDistanceType metric#

Distance type.

float metric_arg#

The argument used by some distance metrics.

bool add_data_on_build#

Whether to add the dataset content to the index, i.e.:

  • true means the index is filled with the dataset vectors and ready to search after calling build.

  • false means build only trains the underlying model (e.g. quantizer or clustering), but the index is left empty; you’d need to call extend on the index afterwards to populate it.

uint32_t n_lists#

The number of inverted lists (clusters)

uint32_t kmeans_n_iters#

The number of iterations searching for kmeans centers (index building).

uint32_t max_train_points_per_cluster#

The number of data vectors per cluster to use during iterative kmeans building. The index uses at most n_lists * max_train_points_per_cluster rows for training.

bool conservative_memory_allocation#

By default, the algorithm allocates more space than necessary for individual clusters (list_data). This allows to amortize the cost of memory allocation and reduce the number of data copies during repeated calls to extend (extending the database).

The alternative is the conservative allocation behavior; when enabled, the algorithm always allocates the minimum amount of memory required to store the given number of records. Set this flag to true if you prefer to use as little GPU memory for the database as possible.

Index search parameters#

CUVS_EXPORT cuvsError_t cuvsIvfSqSearchParamsCreate (cuvsIvfSqSearchParams_t *params)

Allocate IVF-SQ search params, and populate with default values.

Parameters:

params – [in] cuvsIvfSqSearchParams_t to allocate

Returns:

cuvsError_t

CUVS_EXPORT cuvsError_t cuvsIvfSqSearchParamsDestroy (cuvsIvfSqSearchParams_t params)

De-allocate IVF-SQ search params.

Parameters:

params – [in]

Returns:

cuvsError_t

struct cuvsIvfSqSearchParams#
#include <ivf_sq.h>

Supplemental parameters to search IVF-SQ index.

Public Members

uint32_t n_probes#

The number of clusters to search.

Index#

typedef cuvsIvfSqIndex *cuvsIvfSqIndex_t#
CUVS_EXPORT cuvsError_t cuvsIvfSqIndexCreate (cuvsIvfSqIndex_t *index)

Allocate IVF-SQ index.

Parameters:

index – [in] cuvsIvfSqIndex_t to allocate

Returns:

cuvsError_t

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexDestroy (cuvsIvfSqIndex_t index)

De-allocate IVF-SQ index.

Parameters:

index – [in] cuvsIvfSqIndex_t to de-allocate

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetNLists (cuvsIvfSqIndex_t index, int64_t *n_lists)

Get the number of clusters/inverted lists

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetDim (cuvsIvfSqIndex_t index, int64_t *dim)

Get the dimensionality of the data

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetSize (cuvsIvfSqIndex_t index, int64_t *size)

Get the size of the index

CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetCenters (cuvsIvfSqIndex_t index, DLManagedTensor *centers)

Get the cluster centers corresponding to the lists [n_lists, dim].

Parameters:
  • index – [in] cuvsIvfSqIndex_t Built Ivf-SQ Index

  • centers – [out] Preallocated array on host or device memory to store output, [n_lists, dim]

Returns:

cuvsError_t

struct cuvsIvfSqIndex#
#include <ivf_sq.h>

Struct to hold address of cuvs::neighbors::ivf_sq::index and its active trained dtype.

Index build#

CUVS_EXPORT cuvsError_t cuvsIvfSqBuild (cuvsResources_t res, cuvsIvfSqIndexParams_t index_params, DLManagedTensor *dataset, cuvsIvfSqIndex_t index)

Build an IVF-SQ index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are:

  1. kDLDataType.code == kDLFloat and kDLDataType.bits = 32

  2. kDLDataType.code == kDLFloat and kDLDataType.bits = 16

#include <cuvs/core/c_api.h>
#include <cuvs/neighbors/ivf_sq.h>

// Create cuvsResources_t
cuvsResources_t res;
cuvsError_t res_create_status = cuvsResourcesCreate(&res);

// Assume a populated `DLManagedTensor` type here
DLManagedTensor dataset;

// Create default index params
cuvsIvfSqIndexParams_t index_params;
cuvsError_t params_create_status = cuvsIvfSqIndexParamsCreate(&index_params);

// Create IVF-SQ index
cuvsIvfSqIndex_t index;
cuvsError_t index_create_status = cuvsIvfSqIndexCreate(&index);

// Build the IVF-SQ Index
cuvsError_t build_status = cuvsIvfSqBuild(res, index_params, &dataset, index);

// de-allocate `index_params`, `index` and `res`
cuvsError_t params_destroy_status = cuvsIvfSqIndexParamsDestroy(index_params);
cuvsError_t index_destroy_status = cuvsIvfSqIndexDestroy(index);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);
Parameters:
  • res – [in] cuvsResources_t opaque C handle

  • index_params – [in] cuvsIvfSqIndexParams_t used to build IVF-SQ index

  • dataset – [in] DLManagedTensor* training dataset

  • index – [out] cuvsIvfSqIndex_t Newly built IVF-SQ index

Returns:

cuvsError_t

Index extend#

CUVS_EXPORT cuvsError_t cuvsIvfSqExtend (cuvsResources_t res, DLManagedTensor *new_vectors, DLManagedTensor *new_indices, cuvsIvfSqIndex_t index)

Extend the index with the new data.

Parameters:
  • res – [in] cuvsResources_t opaque C handle

  • new_vectors – [in] DLManagedTensor* the new vectors to add to the index

  • new_indices – [in] DLManagedTensor* vector of new indices for the new vectors. If the index is empty, this can be NULL to imply a continuous range [0...n_rows).

  • index – [inout] IVF-SQ index to be extended

Returns:

cuvsError_t

Index serialize#

CUVS_EXPORT cuvsError_t cuvsIvfSqSerialize (cuvsResources_t res, const char *filename, cuvsIvfSqIndex_t index)

Save the index to file.

Experimental, both the API and the serialization format are subject to change.

#include <cuvs/neighbors/ivf_sq.h>

// Create cuvsResources_t
cuvsResources_t res;
cuvsError_t res_create_status = cuvsResourcesCreate(&res);

// create an index with `cuvsIvfSqBuild`
cuvsIvfSqSerialize(res, "/path/to/index", index);
Parameters:
  • res – [in] cuvsResources_t opaque C handle

  • filename – [in] the file name for saving the index

  • index – [in] IVF-SQ index

CUVS_EXPORT cuvsError_t cuvsIvfSqDeserialize (cuvsResources_t res, const char *filename, cuvsIvfSqIndex_t index)

Load index from file.

Experimental, both the API and the serialization format are subject to change.

Parameters:
  • res – [in] cuvsResources_t opaque C handle

  • filename – [in] the name of the file that stores the index

  • index – [out] IVF-SQ index loaded from disk