manifold_vectors/
lib.rs

1//! # manifold-vectors
2//!
3//! Vector storage optimizations for the Manifold embedded database.
4//!
5//! This crate provides ergonomic, type-safe wrappers around Manifold's core primitives
6//! for storing and retrieving vector embeddings commonly used in ML/AI applications.
7//!
8//! ## Features
9//!
10//! - **Zero-copy access**: Fixed-dimension vectors leverage Manifold's `fixed_width()` trait
11//!   for direct memory-mapped access without deserialization overhead
12//! - **Type safety**: Compile-time dimension checking via const generics
13//! - **High performance**: Bulk operations, efficient encoding, WAL group commit
14//! - **Multiple formats**: Dense, sparse (COO), and multi-vector (ColBERT-style) support
15//! - **Integration-ready**: Traits for external index libraries (HNSW, FAISS, etc.)
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use manifold::column_family::ColumnFamilyDatabase;
21//! use manifold_vectors::{VectorTable, distance};
22//! use manifold_vectors::dense::VectorTableRead;
23//! use uuid::Uuid;
24//!
25//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
26//! let db = ColumnFamilyDatabase::open("my.db")?;
27//! let cf = db.column_family_or_create("embeddings")?;
28//!
29//! let doc_id = Uuid::new_v4();
30//!
31//! // Write vectors
32//! {
33//!     let write_txn = cf.begin_write()?;
34//!     let mut vectors = VectorTable::<768>::open(&write_txn, "vectors")?;
35//!     let embedding = [0.1f32; 768];
36//!     vectors.insert(&doc_id, &embedding)?;
37//!     drop(vectors);
38//!     write_txn.commit()?;
39//! }
40//!
41//! // Read with zero-copy access - no allocations!
42//! let read_txn = cf.begin_read()?;
43//! let vectors = VectorTableRead::<768>::open(&read_txn, "vectors")?;
44//!
45//! if let Some(guard) = vectors.get(&doc_id)? {
46//!     // guard provides zero-copy access to mmap'd data
47//!     let query = [0.1f32; 768];
48//!     let similarity = distance::cosine(&query, guard.value());
49//!     println!("Cosine similarity: {}", similarity);
50//!     // guard dropped here - no malloc/free occurred!
51//! }
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! ## Architecture
57//!
58//! This crate does **not** implement vector indexing algorithms (HNSW, IVF, PQ, etc.).
59//! Instead, it focuses on efficient storage and provides integration traits for external
60//! libraries. For approximate nearest neighbor search, use libraries like:
61//!
62//! - [`instant-distance`](https://crates.io/crates/instant-distance) - Pure Rust HNSW
63//! - [`hnswlib`](https://crates.io/crates/hnswlib) - Bindings to C++ hnswlib
64//!
65//! See the examples directory for integration patterns.
66
67#![deny(missing_docs)]
68#![deny(clippy::all, clippy::pedantic)]
69#![allow(
70    clippy::module_name_repetitions,
71    clippy::must_use_candidate,
72    clippy::missing_errors_doc,
73    clippy::missing_panics_doc
74)]
75
76pub mod dense;
77pub mod distance;
78pub mod integration;
79pub mod multi;
80pub mod sparse;
81
82pub use dense::{VectorGuard, VectorTable, VectorTableRead};
83pub use multi::{MultiVectorTable, MultiVectorTableRead};
84pub use sparse::{SparseVector, SparseVectorTable, SparseVectorTableRead};
manifold_vectors/lib.rs

manifold_vectors/
lib.rs
