nitrite_vector 0.4.2

Vector / HNSW ANN indexing and RAG store for the Nitrite database
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

//! # Nitrite Vector — HNSW ANN index & RAG store for Nitrite
//!
//! This crate adds an approximate-nearest-neighbour (ANN) vector index to the
//! Nitrite embedded database, backed by a hand-rolled, persistent
//! **HNSW** (Hierarchical Navigable Small World) graph, plus a thin
//! [`RagStore`] convenience layer for retrieval-augmented-generation workloads.
//!
//! Embeddings are **provided by the caller** (bring-your-own vectors); this
//! crate does not generate embeddings.
//!
//! ## Quick start (raw collection API)
//!
//! ```rust,ignore
//! use nitrite::nitrite::Nitrite;
//! use nitrite::common::PersistentCollection;
//! use nitrite_vector::{VectorModule, VectorIndexConfig, vector_index_options, vector_field};
//! use nitrite_vector::distance::Metric;
//!
//! let db = Nitrite::builder()
//!     .load_module(VectorModule::new(VectorIndexConfig::new(3, Metric::Cosine)))
//!     .open_or_create(None, None)?;
//!
//! let collection = db.collection("docs")?;
//! collection.create_index(vec!["embedding"], &vector_index_options())?;
//!
//! // ... insert documents whose `embedding` field is a numeric array ...
//!
//! let filter = vector_field("embedding").nearest(vec![0.1, 0.2, 0.3], 5).build();
//! let results = collection.find(filter)?;
//! ```
//!
//! ## RAG store
//!
//! ```rust,ignore
//! use nitrite_vector::RagStore;
//! use nitrite_vector::distance::Metric;
//!
//! // `Metric::Cosine` must match the metric configured on the VectorModule.
//! let store = RagStore::create(&db, "kb", Metric::Cosine)?;
//! store.add("hello world", embedding, doc!{ "source": "wiki" })?;
//! let hits = store.search(query_vector, 5).run()?;
//! ```
//!
//! ## Security note
//!
//! Vectors are stored **in plaintext** by both backends (embeddings are
//! generally invertible back to content — treat them as the data itself). The
//! DiskANN backend writes its files next to the database, outside whatever the
//! storage adapter provides, and therefore requires a persistent `db_path`.

pub mod diskann;
pub mod distance;
pub mod filter;
pub mod fluent;
pub mod hnsw;
pub mod indexer;
pub mod module;
pub mod node;
pub mod precision;
pub mod rag;
pub mod vector_index;

pub use diskann::{DiskAnnConfig, DiskAnnIndex};
pub use distance::Metric;
pub use filter::{value_to_vector, vector_to_value, VectorNearestFilter, VECTOR_INDEX};
pub use fluent::{vector_field, VectorFluentFilter, VectorNearestBuilder};
pub use indexer::VectorIndexer;
pub use module::{VectorModule, VectorModuleBuilder};
pub use precision::Precision;
pub use rag::{RagStore, SearchHit, SearchQuery};
pub use vector_index::{
    derive_vector_map_name, HnswBackend, IndexBackend, VectorIndex, VectorIndexConfig,
};

/// Creates [`IndexOptions`](nitrite::index::IndexOptions) for a vector index.
///
/// Use with `collection.create_index(vec!["embedding"], &vector_index_options())`.
pub fn vector_index_options() -> nitrite::index::IndexOptions {
    nitrite::index::IndexOptions::new(VECTOR_INDEX)
}