Struct RingDb 

pub struct RingDb<T: Payload = ()> { /* private fields */ }

Builder for a ring-query vector database.

Insert vectors with their associated payloads via add_vector(), then call build() to obtain a SealedRingDb.

T must implement Payload, which is derived with #[derive(Payload)]. Use T = () when no payload is needed.

Example — no payload

use ringdb::{RingDb, RingDbConfig, RingQuery};

let mut db = RingDb::new(RingDbConfig::new(4)).unwrap();
db.add_vector(&[1.0, 0.0, 0.0, 0.0], ()).unwrap();
db.add_vector(&[0.0, 1.0, 0.0, 0.0], ()).unwrap();

let db = db.build().unwrap();
let result = db.query(&RingQuery { query: &[1.0f32, 0.0, 0.0, 0.0], d: 1.0, lambda: 0.1 }).unwrap();
println!("hits: {:?}", result.ids);

Implementations

impl<T: Payload> RingDb<T>

pub fn new(config: RingDbConfig) -> Result<Self>

Create a new empty RingDb.

The storage strategy (Serde or Pod) is determined entirely by T’s #[derive(Payload)] — no second constructor needed.

Example — with Serde payload

use ringdb::{RingDb, RingDbConfig, RingQuery, Payload};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Payload)]
struct Meta { label: String }

let mut db: RingDb<Meta> = RingDb::new(RingDbConfig::new(2)).unwrap();
db.add_vector(&[1.0, 0.0], Meta { label: "dog".into() }).unwrap();
db.add_vector(&[0.0, 1.0], Meta { label: "cat".into() }).unwrap();

let db = db.build().unwrap();
let result = db.query(&RingQuery { query: &[1.0f32, 0.0], d: 1.0, lambda: 0.1 }).unwrap();
let payloads = db.fetch_payloads(&result.ids).unwrap();

pub fn add_vector(&mut self, vector: &[f32], payload: T) -> Result<()>

Insert a single vector and its associated payload.

Vectors are assigned sequential IDs starting from 0. The slice length must equal dims.

pub fn build(self) -> Result<SealedRingDb<T>>

Seal the database.

Transfers vectors to the compute backend and flushes the payload builder to its mmap. If RingDbConfig::persist_dir is set, all data is also written to disk (reload with RingDb::load).

pub fn load( dir: &Path, backend_preference: BackendPreference, ) -> Result<SealedRingDb<T>>

Reconstruct a SealedRingDb from a directory previously written by build() with a persist dir configured.

The correct store variant is selected automatically based on T’s Payload impl — no separate load_pod method needed.

Example

use ringdb::{RingDb, RingDbConfig, BackendPreference};
use std::path::Path;

// --- save ---
let mut db = RingDb::<()>::new(RingDbConfig::new(4).with_persist_dir("/tmp/mydb")).unwrap();
db.add_vector(&[1.0, 0.0, 0.0, 0.0], ()).unwrap();
let _sealed = db.build().unwrap();

// --- load ---
let loaded = RingDb::<()>::load(Path::new("/tmp/mydb"), BackendPreference::Cpu).unwrap();

pub fn len(&self) -> usize

Number of vectors currently staged.

pub fn is_empty(&self) -> bool

Returns true if no vectors have been inserted.

pub fn dims(&self) -> usize

Number of dimensions per vector.

pub fn backend_name(&self) -> &str

Name of the backend currently in use.