Neighbors Cagra Index Module

Rust module: cuvs::neighbors::cagra::index

Source: rust/cuvs/src/neighbors/cagra/index.rs

Index

1
#[derive(Debug)]
2
pub struct Index<'d> {
3
    /* private fields */
4
}

A CAGRA approximate nearest neighbor index.

The lifetime 'd ties this index to the underlying dataset, passed at construction time. The C library may store a non-owning view of properly aligned device-resident data, so the dataset must outlive the index. When an index is deserialized from disk, the data is self-contained and its lifetime is 'static.

Methods

build

1
pub fn build<T>(res: &Resources, params: &IndexParams, dataset: &'d T) -> Result<Index<'d>>
2
where
3
T: AsDlTensor + ?Sized,

Builds a CAGRA index over dataset for efficient search.

dataset is a row-major matrix on the host or device implementing [AsDlTensor]. The C++ index keeps a non-owning view of it, so the returned [Index] borrows dataset for 'd and cannot outlive it.

Source: rust/cuvs/src/neighbors/cagra/index.rs:45

search

1
pub fn search<Q, N, D>(
2
&self,
3
res: &Resources,
4
params: &SearchParams,
5
queries: &Q,
6
neighbors: &mut N,
7
distances: &mut D,
8
) -> Result<()>
9
where
10
Q: AsDlTensor + ?Sized,
11
N: AsDlTensorMut + ?Sized,
12
D: AsDlTensorMut + ?Sized,

Searches the index for the k nearest neighbors of each query.

queries, neighbors, and distances must reside in device memory and implement [AsDlTensor] / [AsDlTensorMut]. neighbors (shape n_queries × k) receives the neighbor indices and distances their distances; both are written in place.

Source: rust/cuvs/src/neighbors/cagra/index.rs:77

search_filtered

1
pub fn search_filtered<Q, N, D>(
2
&self,
3
res: &Resources,
4
params: &SearchParams,
5
queries: &Q,
6
neighbors: &mut N,
7
distances: &mut D,
8
filter: &Filter<'_, Bitset>,
9
) -> Result<()>
10
where
11
Q: AsDlTensor + ?Sized,
12
N: AsDlTensorMut + ?Sized,
13
D: AsDlTensorMut + ?Sized,

Searches the index with a row-level bitset filter.

Source: rust/cuvs/src/neighbors/cagra/index.rs:97

serialize

1
pub fn serialize<P: AsRef<Path>>(
2
&self,
3
res: &Resources,
4
filename: P,
5
include_dataset: bool,
6
) -> Result<()>

Save the CAGRA index to file.

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

Arguments

• res - Resources to use
• filename - The file path for saving the index
• include_dataset - Whether to write out the dataset to the file

Example:

use cuvs::Resources;
use cuvs::neighbors::cagra::{Index, IndexParams};
fn serialize_example() -> Result<(), Box<dyn std::error::Error>> {
let res = Resources::new()?;
// Build an index (using some dataset)
let build_params = IndexParams::builder().build()?;
// let index = Index::build(&res, &build_params, &dataset)?;
// Save the index to disk (including the dataset)
// index.serialize(&res, "/path/to/index.bin", true)?;
// Later, load the index from disk
let loaded_index = Index::deserialize(&res, "/path/to/index.bin")?;
// The loaded index can be used for search just like the original
Ok(())
}

Source: rust/cuvs/src/neighbors/cagra/index.rs:174

serialize_to_hnswlib

1
pub fn serialize_to_hnswlib<P: AsRef<Path>>(&self, res: &Resources, filename: P) -> Result<()>

Save the CAGRA index to file in hnswlib format.

NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib.

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

Arguments

• res - Resources to use
• filename - The file path for saving the index

Source: rust/cuvs/src/neighbors/cagra/index.rs:198

deserialize

1
pub fn deserialize<P: AsRef<Path>>(res: &Resources, filename: P) -> Result<Index<'static>>

Load a CAGRA index from file.

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

Arguments

• res - Resources to use
• filename - The path of the file that stores the index

Source: rust/cuvs/src/neighbors/cagra/index.rs:214

Source: rust/cuvs/src/neighbors/cagra/index.rs:27