ring-db 0.3.0

A Rust library for ring queries in high-dimensional vector spaces.
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

use std::path::PathBuf;

/// Which compute backend to use for ring queries.
///
/// Only CPU is supported for now. This enum exists so the config is ready
/// to be extended with additional backends later.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum BackendPreference {
    /// CPU brute-force (always available).
    #[default]
    Cpu,
}

/// Configuration for a `RingDb` instance.
#[derive(Debug, Clone)]
pub struct RingDbConfig {
    /// Number of dimensions per vector. Must be > 0.
    pub dims: usize,
    /// Backend selection strategy.
    pub backend_preference: BackendPreference,
    /// Optional directory for persisting the database.
    ///
    /// When set, [`RingDb::build()`](crate::engine::RingDb::build) writes the
    /// full database (vectors, norms, payloads, offsets, and metadata) to this
    /// directory. The sealed database can later be reloaded with
    /// [`RingDb::load()`](crate::engine::RingDb::load).
    ///
    /// Leave `None` (the default) for a purely in-memory database.
    pub persist_dir: Option<PathBuf>,
}

impl RingDbConfig {
    /// Create a config with default settings (CPU backend, no persistence).
    pub fn new(dims: usize) -> Self {
        Self {
            dims,
            backend_preference: BackendPreference::Cpu,
            persist_dir: None,
        }
    }

    /// Set the directory to which the database will be persisted on
    /// [`build()`](crate::engine::RingDb::build).
    ///
    /// The directory is created automatically if it does not exist.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ringdb::RingDbConfig;
    ///
    /// let config = RingDbConfig::new(128).with_persist_dir("/var/data/mydb");
    /// ```
    pub fn with_persist_dir(mut self, dir: impl Into<PathBuf>) -> Self {
        self.persist_dir = Some(dir.into());
        self
    }

    /// Set the backend preference.
    ///
    /// Defaults to [`BackendPreference::Cpu`]. Use this when loading a
    /// persisted database onto a specific backend via [`RingDb::load()`](crate::engine::RingDb::load).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ringdb::RingDbConfig;
    /// use ringdb::BackendPreference;
    ///
    /// let config = RingDbConfig::new(128).with_backend_preference(BackendPreference::Cpu);
    /// ```
    pub fn with_backend_preference(mut self, preference: BackendPreference) -> Self {
        self.backend_preference = preference;
        self
    }
}