Struct Index

pub struct Index { /* private fields */ }

Approximate Nearest Neighbors search index for dense vectors.

The Index struct provides an abstraction over a dense vector space, allowing for efficient addition, search, and management of high-dimensional vectors. It supports various distance metrics and vector types through generic interfaces.

Examples

Basic usage:

use usearch::{Index, IndexOptions, MetricKind, ScalarKind};

let mut options = IndexOptions::default();
options.dimensions = 4; // Set the number of dimensions for vectors
options.metric = MetricKind::Cos; // Use cosine similarity for distance measurement
options.quantization = ScalarKind::F32; // Use 32-bit floating point numbers

let index = Index::new(&options).expect("Failed to create index.");
index.reserve(1000).expect("Failed to reserve capacity.");

// Add vectors to the index
let vector1: Vec<f32> = vec![0.0, 1.0, 0.0, 1.0];
let vector2: Vec<f32> = vec![1.0, 0.0, 1.0, 0.0];
index.add(1, &vector1).expect("Failed to add vector1.");
index.add(2, &vector2).expect("Failed to add vector2.");

// Search for the nearest neighbors to a query vector
let query: Vec<f32> = vec![0.5, 0.5, 0.5, 0.5];
let results = index.search(&query, 5).expect("Search failed.");
for (key, distance) in results.keys.iter().zip(results.distances.iter()) {
    println!("Key: {}, Distance: {}", key, distance);
}

For more examples, including how to add vectors to the index and perform searches, refer to the individual method documentation.

Implementations

impl Index

pub fn new(options: &IndexOptions) -> Result<Self, Exception>

pub fn expansion_add(self: &Index) -> usize

Retrieves the expansion value used during index creation.

pub fn expansion_search(self: &Index) -> usize

Retrieves the expansion value used during search.

pub fn change_expansion_add(self: &Index, n: usize)

Updates the expansion value used during index creation. Rarely used.

pub fn change_expansion_search(self: &Index, n: usize)

Updates the expansion value used during search operations.

pub fn change_metric_kind(self: &Index, metric: MetricKind)

Changes the metric kind used to calculate the distance between vectors.

pub fn change_metric<T: VectorType>( self: &mut Index, metric: Box<dyn Fn(*const T, *const T) -> Distance + Send + Sync>, )

Overrides the metric function used to calculate the distance between vectors.

pub fn hardware_acceleration(&self) -> String

Retrieves the hardware acceleration information.

pub fn search<T: VectorType>( self: &Index, query: &[T], count: usize, ) -> Result<Matches, Exception>

Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query.

Arguments

• query - A slice containing the query vector data.
• count - The maximum number of neighbors to search for.

Returns

A Result containing the matches found.

pub fn filtered_search<T: VectorType, F>( self: &Index, query: &[T], count: usize, filter: F, ) -> Result<Matches, Exception>

where F: Fn(Key) -> bool,

Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query satisfying a custom filter function.

Arguments

• query - A slice containing the query vector data.
• count - The maximum number of neighbors to search for.
• filter - A closure that takes a Key and returns true if the corresponding vector should be included in the search results, or false otherwise.

Returns

A Result containing the matches found.

pub fn add<T: VectorType>( self: &Index, key: Key, vector: &[T], ) -> Result<(), Exception>

Adds a vector with a specified key to the index.

Arguments

• key - The key associated with the vector.
• vector - A slice containing the vector data.

pub fn get<T: VectorType>( self: &Index, key: Key, vector: &mut [T], ) -> Result<usize, Exception>

Extracts one or more vectors matching the specified key. The vector slice must be a multiple of the number of dimensions in the index. After the execution, return the number X of vectors found. The vector slice’s first X * dimensions elements will be filled.

If you are a novice user, consider export.

Arguments

• key - The key associated with the vector.
• vector - A slice containing the vector data.

pub fn export<T: VectorType + Default + Clone>( self: &Index, key: Key, vector: &mut Vec<T>, ) -> Result<usize, Exception>

Extracts one or more vectors matching specified key into supplied resizable vector. The vector is resized to a multiple of the number of dimensions in the index.

Arguments

• key - The key associated with the vector.
• vector - A mutable vector containing the vector data.

pub fn reserve(self: &Index, capacity: usize) -> Result<(), Exception>

Reserves memory for a specified number of incoming vectors.

Arguments

• capacity - The desired total capacity, including the current size.

pub fn dimensions(self: &Index) -> usize

Retrieves the number of dimensions in the vectors indexed.

pub fn connectivity(self: &Index) -> usize

Retrieves the connectivity parameter that limits connections-per-node in the graph.

pub fn size(self: &Index) -> usize

Retrieves the current number of vectors in the index.

pub fn capacity(self: &Index) -> usize

Retrieves the total capacity of the index, including reserved space.

pub fn serialized_length(self: &Index) -> usize

Reports expected file size after serialization.

pub fn remove(self: &Index, key: Key) -> Result<usize, Exception>

Removes the vector associated with the given key from the index.

Arguments

• key - The key of the vector to be removed.

Returns

true if the vector is successfully removed, false otherwise.

pub fn rename(self: &Index, from: Key, to: Key) -> Result<usize, Exception>

Renames the vector under a specific key.

Arguments

• from - The key of the vector to be renamed.
• to - The new name.

Returns

true if the vector is renamed, false otherwise.

pub fn contains(self: &Index, key: Key) -> bool

Checks if the index contains a vector with a specified key.

Arguments

• key - The key to be checked.

Returns

true if the index contains the vector with the given key, false otherwise.

pub fn count(self: &Index, key: Key) -> usize

Count the count of vectors with the same specified key.

Arguments

• key - The key to be checked.

Returns

Number of vectors found.

pub fn save(self: &Index, path: &str) -> Result<(), Exception>

Saves the index to a specified file.

Arguments

• path - The file path where the index will be saved.

pub fn load(self: &Index, path: &str) -> Result<(), Exception>

Loads the index from a specified file.

Arguments

• path - The file path from where the index will be loaded.

pub fn view(self: &Index, path: &str) -> Result<(), Exception>

Creates a view of the index from a file without loading it into memory.

Arguments

• path - The file path from where the view will be created.

pub fn reset(self: &Index) -> Result<(), Exception>

Erases all members from the index, closes files, and returns RAM to OS.

pub fn memory_usage(self: &Index) -> usize

A relatively accurate lower bound on the amount of memory consumed by the system. In practice, its error will be below 10%.

pub fn save_to_buffer(self: &Index, buffer: &mut [u8]) -> Result<(), Exception>

Saves the index to a specified file.

Arguments

• buffer - The buffer where the index will be saved.

pub fn load_from_buffer(self: &Index, buffer: &[u8]) -> Result<(), Exception>

Loads the index from a specified file.

Arguments

• buffer - The buffer from where the index will be loaded.

pub unsafe fn view_from_buffer( self: &Index, buffer: &[u8], ) -> Result<(), Exception>

Creates a view of the index from a file without loading it into memory.

Arguments

• buffer - The buffer from where the view will be created.

Safety

This function is marked as unsafe because it stores a pointer to the input buffer. The caller must ensure that the buffer outlives the index and is not dropped or modified for the duration of the index’s use. Dereferencing a pointer to a temporary buffer after it has been dropped can lead to undefined behavior, which violates Rust’s memory safety guarantees.

Example of misuse:

let index: usearch::Index = usearch::new_index(&usearch::IndexOptions::default()).unwrap();

let temporary = vec![0u8; 100];
index.view_from_buffer(&temporary);
std::mem::drop(temporary);

let query = vec![0.0; 256];
let results = index.search(&query, 5).unwrap();

The above example would result in use-after-free and undefined behavior.

Trait Implementations

impl Send for Index

impl Sync for Index