Crate granne[−][src]
Expand description
Granne (graph-based retrieval of approximate nearest neighbors) provides approximate nearest neighbor search among (typically) high-dimensional vectors. It focuses on reducing memory usage in order to allow indexing billions of vectors.
Note: There is currently a limit on the number of elements that can be indexed: 2^32 - 2 == 4_294_967_294
.
Overview
Granne
is the main struct used for querying/searching for nearest neighbors.GranneBuilder
is used to buildGranne
indexes.Index
andBuilder
are traits implemented for allGranne
andGranneBuilder
types, since bothGranne
andGranneBuilder
are generic over the type of elements.SumEmbeddings
support the use case where the element are constructed by summing a smaller number of embeddings.
Memory-mapping
Granne uses memory-mapping for both index and elements. This makes it possible to lazy-load and use the index without loading all of it into memory (or share the index between different process).
Unfortunately, memory-mapping requires unsafe
code to load the index/elements. The reason is that Granne
cannot guarantee that the underlying file is not modified (by some other thread or process) while being memory-mapped.
For more information on the unsafe:ness of memmap
, please see the memmap
crate or refer to this discussion on
users.rust-lang.org.
Examples
Basic building, saving and loading
For information on how to read/load/create elements see e.g. angular
or the glove.rs
example.
use granne::{Granne, GranneBuilder, Index, Builder, BuildConfig, angular}; let elements: angular::Vectors = /* omitted */ // building the index let mut builder = GranneBuilder::new(BuildConfig::default(), elements); builder.build(); // saving to disk let mut index_file = tempfile::tempfile()?; builder.write_index(&mut index_file)?; let mut elements_file = tempfile::tempfile()?; builder.write_elements(&mut elements_file)?; // loading (memory-mapping) index and vectors let elements = unsafe { angular::Vectors::from_file(&elements_file)? }; let index = unsafe { Granne::from_file(&index_file, elements)? }; // max_search controls how extensive the search is let max_search = 200; let res = index.search(&random_vector, max_search, num_results); assert_eq!(num_results, res.len());
Modules
angular | This module contains element types for angular vectors using |
angular_int | This module contains element types for quantized angular vectors using |
embeddings | A module for elements that can be embedded into vector spaces. |
Structs
BuildConfig |
|
Granne | An index for fast approximate nearest neighbor search.
The index is built by using |
GranneBuilder | A builder for creating an index to be searched using |
Traits
Builder | This trait is implemented for any |
Dist |
|
ElementContainer | A trait for any type containing elements to be indexed using |
ExtendableElementContainer | A trait for |
Index | This trait is implemented for any |
Permutable | A trait for |
Writeable | A trait for types that are writeable to a buffer |