velesdb_core/storage/
traits.rs

1//! Storage traits for vectors and payloads.
2//!
3//! This module defines the core storage abstractions used by `VelesDB`.
4
5use std::io;
6
7/// Trait defining storage operations for vectors.
8pub trait VectorStorage: Send + Sync {
9    /// Stores a vector with the given ID.
10    ///
11    /// Durability note: implementations may buffer writes. Call [`flush`](Self::flush)
12    /// to obtain an explicit durability barrier.
13    ///
14    /// # Errors
15    ///
16    /// Returns an error if the write operation fails.
17    fn store(&mut self, id: u64, vector: &[f32]) -> io::Result<()>;
18
19    /// Stores multiple vectors in a single batch operation.
20    ///
21    /// This is optimized for bulk imports:
22    /// - Single WAL write for the entire batch
23    /// - Contiguous memory writes
24    ///
25    /// Durability note: batch writes may be buffered. Call [`flush`](Self::flush)
26    /// after `store_batch` to force persistence guarantees.
27    ///
28    /// # Errors
29    ///
30    /// Returns an error if the write operation fails.
31    fn store_batch(&mut self, vectors: &[(u64, &[f32])]) -> io::Result<usize>;
32
33    /// Retrieves a vector by ID.
34    ///
35    /// # Errors
36    ///
37    /// Returns an error if the read operation fails.
38    fn retrieve(&self, id: u64) -> io::Result<Option<Vec<f32>>>;
39
40    /// Deletes a vector by ID.
41    ///
42    /// # Errors
43    ///
44    /// Returns an error if the delete operation fails.
45    fn delete(&mut self, id: u64) -> io::Result<()>;
46
47    /// Flushes pending writes to disk.
48    ///
49    /// This is the explicit durability barrier. Callers that require
50    /// deterministic crash consistency must call this method.
51    ///
52    /// # Errors
53    ///
54    /// Returns an error if the flush operation fails.
55    fn flush(&mut self) -> io::Result<()>;
56
57    /// Returns the number of vectors stored.
58    fn len(&self) -> usize;
59
60    /// Returns true if the storage is empty.
61    fn is_empty(&self) -> bool {
62        self.len() == 0
63    }
64
65    /// Returns all stored IDs.
66    fn ids(&self) -> Vec<u64>;
67}
68
69/// Trait defining storage operations for metadata payloads.
70pub trait PayloadStorage: Send + Sync {
71    /// Stores a payload with the given ID.
72    ///
73    /// Durability note: implementations may buffer writes. Call [`flush`](Self::flush)
74    /// to obtain an explicit durability barrier.
75    ///
76    /// # Errors
77    ///
78    /// Returns an error if the write operation fails.
79    fn store(&mut self, id: u64, payload: &serde_json::Value) -> io::Result<()>;
80
81    /// Retrieves a payload by ID.
82    ///
83    /// # Errors
84    ///
85    /// Returns an error if the read operation fails.
86    fn retrieve(&self, id: u64) -> io::Result<Option<serde_json::Value>>;
87
88    /// Deletes a payload by ID.
89    ///
90    /// Implementations MAY treat a delete of an unknown id as a no-op
91    /// (returning `Ok(())` without producing a durable record). Callers
92    /// must not rely on this method to emit an audit trail for every call.
93    ///
94    /// # Errors
95    ///
96    /// Returns an error if the delete operation fails.
97    fn delete(&mut self, id: u64) -> io::Result<()>;
98
99    /// Flushes pending writes to disk.
100    ///
101    /// This is the explicit durability barrier. Callers that require
102    /// deterministic crash consistency must call this method.
103    ///
104    /// # Errors
105    ///
106    /// Returns an error if the flush operation fails.
107    fn flush(&mut self) -> io::Result<()>;
108
109    /// Returns all stored IDs.
110    fn ids(&self) -> Vec<u64>;
111}
velesdb_core/storage/traits.rs

velesdb_core/storage/
traits.rs
