HNSW#

This is a wrapper for hnswlib, to load a CAGRA index as an immutable HNSW index. The loaded HNSW index is only compatible in cuVS, and can be searched using wrapper functions.

#include <raft/neighbors/hnsw.h>

Index search parameters#

typedef struct cuvsHnswSearchParams *cuvsHnswSearchParams_t#

cuvsError_t cuvsHnswSearchParamsCreate(cuvsHnswSearchParams_t *params)#

Allocate HNSW search params, and populate with default values.

Parameters:: params – [in] cuvsHnswSearchParams_t to allocate
Returns:: cuvsError_t

cuvsError_t cuvsHnswSearchParamsDestroy(cuvsHnswSearchParams_t params)#

De-allocate HNSW search params.

Parameters:: params – [in] cuvsHnswSearchParams_t to de-allocate
Returns:: cuvsError_t

struct cuvsHnswSearchParams#: #include <hnsw.h>

Index#

typedef cuvsHnswIndex *cuvsHnswIndex_t#

cuvsError_t cuvsHnswIndexCreate(cuvsHnswIndex_t *index)#

Allocate HNSW index.

Parameters:: index – [in] cuvsHnswIndex_t to allocate
Returns:: HnswError_t

cuvsError_t cuvsHnswIndexDestroy(cuvsHnswIndex_t index)#

De-allocate HNSW index.

Parameters:: index – [in] cuvsHnswIndex_t to de-allocate

struct cuvsHnswIndex#: #include <hnsw.h>

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

Index extend parameters#

typedef struct cuvsHnswExtendParams *cuvsHnswExtendParams_t#

cuvsError_t cuvsHnswExtendParamsCreate(cuvsHnswExtendParams_t *params)#

Allocate HNSW extend params, and populate with default values.

Parameters:: params – [in] cuvsHnswExtendParams_t to allocate
Returns:: cuvsError_t

cuvsError_t cuvsHnswExtendParamsDestroy(cuvsHnswExtendParams_t params)#

De-allocate HNSW extend params.

Parameters:: params – [in] cuvsHnswExtendParams_t to de-allocate
Returns:: cuvsError_t

struct cuvsHnswExtendParams#

#include <hnsw.h>

Public Members

int num_threads#: Number of CPU threads used to extend additional vectors

Index extend#

cuvsError_t cuvsHnswExtend(cuvsResources_t res, cuvsHnswExtendParams_t params, DLManagedTensor *additional_dataset, cuvsHnswIndex_t index)#

Add new vectors to an HNSW index NOTE: The HNSW index can only be extended when the hierarchy is CPU when converting from a CAGRA index.

#include <cuvs/core/c_api.h>
#include <cuvs/neighbors/cagra.h>
#include <cuvs/neighbors/hnsw.h>

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

// create an index with `cuvsCagraBuild`

// Convert the CAGRA index to an HNSW index
cuvsHnswIndex_t hnsw_index;
cuvsHnswIndexCreate(&hnsw_index);
cuvsHnswIndexParams_t hnsw_params;
cuvsHnswIndexParamsCreate(&hnsw_params);
cuvsHnswFromCagra(res, hnsw_params, cagra_index, hnsw_index);

// Extend the HNSW index with additional vectors
DLManagedTensor additional_dataset;
cuvsHnswExtendParams_t extend_params;
cuvsHnswExtendParamsCreate(&extend_params);
cuvsHnswExtend(res, extend_params, additional_dataset, hnsw_index);

// de-allocate `hnsw_params`, `hnsw_index`, `extend_params` and `res`
cuvsError_t hnsw_params_destroy_status = cuvsHnswIndexParamsDestroy(hnsw_params);
cuvsError_t hnsw_index_destroy_status = cuvsHnswIndexDestroy(hnsw_index);
cuvsError_t extend_params_destroy_status = cuvsHnswExtendParamsDestroy(extend_params);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);

Parameters:

res – [in] cuvsResources_t opaque C handle
params – [in] cuvsHnswExtendParams_t used to extend Hnsw index
additional_dataset – [in] DLManagedTensor* additional dataset to extend the index
index – [inout] cuvsHnswIndex_t to extend

Returns:

cuvsError_t

Index load#

cuvsError_t cuvsHnswFromCagra(cuvsResources_t res, cuvsHnswIndexParams_t params, cuvsCagraIndex_t cagra_index, cuvsHnswIndex_t hnsw_index)#

Convert a CAGRA Index to an HNSW index. NOTE: When hierarchy is:

NONE: This method uses the filesystem to write the CAGRA index in /tmp/<random_number>.bin before reading it as an hnswlib index, then deleting the temporary file. The returned index is immutable and can only be searched by the hnswlib wrapper in cuVS, as the format is not compatible with the original hnswlib.
CPU: The returned index is mutable and can be extended with additional vectors. The serialized index is also compatible with the original hnswlib library.

#include <cuvs/core/c_api.h>
#include <cuvs/neighbors/cagra.h>
#include <cuvs/neighbors/hnsw.h>

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

// create a CAGRA index with `cuvsCagraBuild`

// Convert the CAGRA index to an HNSW index
cuvsHnswIndex_t hnsw_index;
cuvsHnswIndexCreate(&hnsw_index);
cuvsHnswIndexParams_t hnsw_params;
cuvsHnswIndexParamsCreate(&hnsw_params);
cuvsHnswFromCagra(res, hnsw_params, cagra_index, hnsw_index);

// de-allocate `hnsw_params`, `hnsw_index` and `res`
cuvsError_t hnsw_params_destroy_status = cuvsHnswIndexParamsDestroy(hnsw_params);
cuvsError_t hnsw_index_destroy_status = cuvsHnswIndexDestroy(hnsw_index);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);

Parameters:

res – [in] cuvsResources_t opaque C handle
params – [in] cuvsHnswIndexParams_t used to load Hnsw index
cagra_index – [in] cuvsCagraIndex_t to convert to HNSW index
hnsw_index – [out] cuvsHnswIndex_t to return the HNSW index

Returns:

cuvsError_t

Index search#

cuvsError_t cuvsHnswSearch(cuvsResources_t res, cuvsHnswSearchParams_t params, cuvsHnswIndex_t index, DLManagedTensor *queries, DLManagedTensor *neighbors, DLManagedTensor *distances)#

Search a HNSW index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCPU, kDLCUDAHost, or kDLCUDAManaged. It is also important to note that the HNSW Index must have been built with the same type of queries, such that index.dtype.code == queries.dl_tensor.dtype.code Supported types for input are:

queries: a. kDLDataType.code == kDLFloat and kDLDataType.bits = 32 b. kDLDataType.code == kDLInt and kDLDataType.bits = 8 c. kDLDataType.code == kDLUInt and kDLDataType.bits = 8
neighbors: kDLDataType.code == kDLUInt and kDLDataType.bits = 64
distances: kDLDataType.code == kDLFloat and kDLDataType.bits = 32 NOTE: When hierarchy is NONE, the HNSW index can only be searched by the hnswlib wrapper in cuVS, as the format is not compatible with the original hnswlib.

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

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

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

// Create default search params
cuvsHnswSearchParams_t params;
cuvsError_t params_create_status = cuvsHnswSearchParamsCreate(&params);

// Search the `index` built using `cuvsHnswFromCagra`
cuvsError_t search_status = cuvsHnswSearch(res, params, index, &queries, &neighbors,
&distances);

// de-allocate `params` and `res`
cuvsError_t params_destroy_status = cuvsHnswSearchParamsDestroy(params);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);

Parameters:

res – [in] cuvsResources_t opaque C handle
params – [in] cuvsHnswSearchParams_t used to search Hnsw index
index – [in] cuvsHnswIndex which has been returned by cuvsHnswFromCagra
queries – [in] DLManagedTensor* queries dataset to search
neighbors – [out] DLManagedTensor* output k neighbors for queries
distances – [out] DLManagedTensor* output k distances for queries

Index serialize#

Warning

doxygengroup: Cannot find group “hnsw_c_index_serialize” in doxygen xml output for project “cuvs” from directory: ../../cpp/doxygen/_xml/