Struct RingDb 

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

Builder for a ring-query vector database.

Insert vectors (and their associated payloads) with add_vector(), then call build() to transfer ownership to the compute backend and obtain a SealedRingDb that can be queried.

T is the payload type stored alongside each vector. Use T = () when no payload is needed.

Example — no payload

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

let config = RingDbConfig::new(4);
let mut db = RingDb::new(config).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);

Example — with payload

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

#[derive(Serialize, Deserialize)]
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();

Implementations

impl<T: Serialize + DeserializeOwned> RingDb<T>

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

Create a new empty RingDb with the given configuration.

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

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>, RingDbError>

Transfer ownership of the accumulated data to the compute backend and seal the database.

Vector data is moved into the backend (zero-cost for the CPU backend). Payloads are serialized and moved into a cold anonymous mmap — the staging Vec<T> is dropped immediately after.

If RingDbConfig::persist_dir is set the following files are written to that directory before sealing:

File	Content
meta.bin	dims + n_vectors as little-endian u64
vectors.bin	raw f32 vectors (row-major)
norms_sq.bin	raw f32 squared norms
payloads.bin	concatenated bincode payload bytes
offsets.bin	byte offsets (u64) into payloads.bin

The database can be reloaded later with RingDb::load().

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

Reconstruct a SealedRingDb from a directory previously written by RingDb::build() when RingDbConfig::persist_dir was set.

Reads meta.bin, vectors.bin, norms_sq.bin, payloads.bin, and offsets.bin from dir, re-uploads the vectors and norms to the requested backend, and memory-maps the payload file.

Pass [BackendPreference::Cpu] for the CPU backend (the only option today; CUDA and others will be added later).

Errors

Returns RingDbError::Corrupt if any file is missing, has an unexpected size, or the dimension/count metadata is inconsistent.

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(); // writes files to /tmp/mydb

// --- 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.