Skip to main content

edgestore/engine/
vector.rs

1use std::sync::Arc;
2use std::time::Instant;
3
4use super::{Engine, QueryStats};
5use crate::error::EdgestoreError;
6use crate::types::Lsn;
7use crate::vector::api::{vector_namespace, VectorEngine};
8use crate::vector::distance::Metric;
9use crate::vector::hnsw::HnswIndex;
10use crate::vector::search::{VectorSearchResult, VectorPage};
11use crate::vector::types::{decode_vector_record, encode_vector_record, Dtype, VectorRecord};
12
13impl Engine {
14    /// Build an HNSW index for all vectors in the given namespace.
15    ///
16    /// Scans all vector records in `__vec__{ns}`, builds the graph,
17    /// serializes it to a sidecar file, and caches it in memory.
18    pub fn build_vector_index(&mut self, ns: &[u8]) -> Result<(), EdgestoreError> {
19        let t0 = Instant::now();
20        let vec_ns = vector_namespace(ns);
21
22        // Scan all vectors
23        let all = self.prefix(&vec_ns, b"")?;
24        if all.is_empty() {
25            return Ok(());
26        }
27
28        // Determine dims, dtype, metric from first record
29        let first_rec = decode_vector_record(&all[0].1)
30            .map_err(|e| EdgestoreError::CorruptData(format!("decode vector: {}", e)))?;
31        let dims = first_rec.dims;
32        let dtype = first_rec.dtype;
33        let metric = Metric::L2; // default; could be parameterized
34
35        let mut index = HnswIndex::new(dims, dtype, metric).with_params(16, 100);
36
37        for (key, val) in &all {
38            // `prefix` already returns decoded raw keys (without namespace prefix)
39            let rec = decode_vector_record(val)?;
40            index.insert(key.clone(), rec.data)?;
41        }
42
43        // Write sidecar file
44        let ns_slug = Self::ns_to_slug(ns);
45        let vector_dir = self.config.path.join("vector");
46        std::fs::create_dir_all(&vector_dir)?;
47        let sidecar_path = vector_dir.join(format!("{}.hnsw", ns_slug));
48
49        let serialized = index.serialize();
50        std::fs::write(&sidecar_path, &serialized)?;
51
52        // Persist segment-hash stamp so is_index_stale can detect staleness
53        let current_hash = self.range_merkle_root()?;
54        let stamp_path = sidecar_path.with_extension("stamp");
55        std::fs::write(&stamp_path, current_hash)?;
56
57        // Cache
58        self.vector_indices
59            .write()
60            .unwrap()
61            .insert(ns.to_vec(), std::sync::Arc::new(index));
62
63        let elapsed_ms = t0.elapsed().as_millis() as u64;
64        self.metrics.vector_index_load_nanos.fetch_add(
65            t0.elapsed().as_nanos() as u64,
66            std::sync::atomic::Ordering::Relaxed,
67        );
68
69        if elapsed_ms > 2000 {
70            eprintln!("warning: build_vector_index took {} ms (> 2s)", elapsed_ms);
71        }
72
73        Ok(())
74    }
75
76    /// Preload the HNSW index for a namespace into memory.
77    ///
78    /// Returns true if the index was loaded (or already cached), false if no index exists.
79    pub fn preload_vector_index(&self, ns: &[u8]) -> Result<bool, EdgestoreError> {
80        match self.get_vector_index(ns) {
81            Ok(Some(_)) => Ok(true),
82            Ok(None) => Ok(false),
83            Err(e) => Err(e),
84        }
85    }
86
87    /// Get the HNSW index for a namespace, loading from sidecar if needed.
88    ///
89    /// Uses a two-phase (double-checked) lock: optimistic read lock on the cache,
90    /// write lock only on a cache miss or stale entry. Returns an `Arc` so the
91    /// caller can hold the index after the lock is released.
92    pub(crate) fn get_vector_index(
93        &self,
94        ns: &[u8],
95    ) -> Result<Option<Arc<HnswIndex>>, EdgestoreError> {
96        // Fast read path: already cached and fresh
97        {
98            let indices = self.vector_indices.read().unwrap();
99            if let Some(arc) = indices.get(ns) {
100                if !self.is_index_stale(ns)? {
101                    return Ok(Some(arc.clone()));
102                }
103                // Stale — fall through to write path
104            } else {
105                let ns_slug = Self::ns_to_slug(ns);
106                let sidecar_path = self
107                    .config
108                    .path
109                    .join("vector")
110                    .join(format!("{}.hnsw", ns_slug));
111                if !sidecar_path.exists() {
112                    return Ok(None);
113                }
114                // Sidecar exists but not cached — fall through to write path
115            }
116        }
117
118        // Write path: evict stale or load from disk
119        let mut indices = self.vector_indices.write().unwrap();
120
121        // Double-check after acquiring write lock
122        if let Some(arc) = indices.get(ns) {
123            if !self.is_index_stale(ns)? {
124                return Ok(Some(arc.clone()));
125            }
126            indices.remove(ns);
127            self.metrics
128                .vector_index_stales
129                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
130        }
131
132        let t0 = Instant::now();
133        let ns_slug = Self::ns_to_slug(ns);
134        let sidecar_path = self
135            .config
136            .path
137            .join("vector")
138            .join(format!("{}.hnsw", ns_slug));
139
140        if !sidecar_path.exists() {
141            return Ok(None);
142        }
143
144        let file_bytes = std::fs::metadata(&sidecar_path)
145            .map(|m| m.len())
146            .unwrap_or(0);
147        if file_bytes > self.config.hnsw_max_ram_bytes {
148            eprintln!(
149                "[edgestore] HNSW sidecar for namespace {:?} is {} MB, exceeds hnsw_max_ram_bytes ({} MB); falling back to flat scan",
150                String::from_utf8_lossy(ns),
151                file_bytes / (1024 * 1024),
152                self.config.hnsw_max_ram_bytes / (1024 * 1024),
153            );
154            return Ok(None);
155        }
156
157        let bytes = std::fs::read(&sidecar_path)?;
158        let index = HnswIndex::deserialize(&bytes)?;
159
160        if self.is_index_stale(ns)? {
161            self.metrics
162                .vector_index_stales
163                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
164            return Ok(None);
165        }
166
167        let arc = std::sync::Arc::new(index);
168        indices.insert(ns.to_vec(), arc.clone());
169        self.metrics
170            .vector_index_loads
171            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
172        self.metrics.vector_index_load_nanos.fetch_add(
173            t0.elapsed().as_nanos() as u64,
174            std::sync::atomic::Ordering::Relaxed,
175        );
176
177        Ok(Some(arc))
178    }
179
180    /// Try an HNSW search, returning `None` if no fresh index is available.
181    ///
182    /// Used by `edgestore-tokio` to attempt the fast HNSW path under a read lock
183    /// before falling back to the paged flat scan. The interior `RwLock` on the
184    /// index cache handles lazy loading without needing the outer engine write lock.
185    pub fn try_hnsw_search(
186        &self,
187        ns: &[u8],
188        query: &VectorRecord,
189        k: usize,
190    ) -> Result<Option<Vec<VectorSearchResult>>, EdgestoreError> {
191        if let Some(index) = self.get_vector_index(ns)? {
192            if index.dtype == query.dtype && index.dims == query.dims {
193                let hnsw_results = index.search(&query.data, k, 50)?;
194                return Ok(Some(
195                    hnsw_results
196                        .into_iter()
197                        .map(|(key, distance)| VectorSearchResult { key, distance })
198                        .collect(),
199                ));
200            }
201        }
202        Ok(None)
203    }
204
205    /// Check if the cached HNSW index is stale by comparing segment hashes.
206    fn is_index_stale(&self, ns: &[u8]) -> Result<bool, EdgestoreError> {
207        let sidecar_path = self
208            .config
209            .path
210            .join("vector")
211            .join(format!("{}.hnsw", Self::ns_to_slug(ns)));
212        if !sidecar_path.exists() {
213            return Ok(true);
214        }
215        let stamp_path = sidecar_path.with_extension("stamp");
216        let Ok(stamp) = std::fs::read(&stamp_path) else {
217            return Ok(true);
218        };
219        let current = self.range_merkle_root()?;
220        Ok(stamp != current)
221    }
222
223    /// Search for the k closest vectors to the query in the given namespace.
224    ///
225    /// Uses HNSW when an index exists and is fresh; falls back to flat scan otherwise.
226    pub fn vector_search(
227        &self,
228        ns: &[u8],
229        query: &VectorRecord,
230        k: usize,
231        metric: Metric,
232    ) -> Result<Vec<VectorSearchResult>, EdgestoreError> {
233        // Try HNSW path
234        if let Some(index) = self.get_vector_index(ns)? {
235            if index.dtype == query.dtype && index.dims == query.dims {
236                let hnsw_results = index.search(&query.data, k, 50)?;
237                return Ok(hnsw_results
238                    .into_iter()
239                    .map(|(key, distance)| VectorSearchResult { key, distance })
240                    .collect());
241            }
242        }
243
244        // Fall back to flat scan
245        crate::vector::search::vector_search(self, ns, query, k, metric)
246    }
247
248    /// Vector search with cost accounting. Returns results + [`QueryStats`].
249    ///
250    /// `bytes_scanned` reflects the sum of encoded vector record sizes examined during
251    /// a flat scan. For HNSW paths, only the result set bytes are counted (graph
252    /// traversal does not materialize all vectors).
253    pub fn vector_search_with_stats(
254        &self,
255        ns: &[u8],
256        query: &VectorRecord,
257        k: usize,
258        metric: Metric,
259    ) -> Result<(Vec<VectorSearchResult>, QueryStats), EdgestoreError> {
260        // HNSW path — stats are approximate (graph traversal not fully instrumented).
261        if let Some(index) = self.get_vector_index(ns)? {
262            if index.dtype == query.dtype && index.dims == query.dims {
263                let hnsw_results = index.search(&query.data, k, 50)?;
264                let results: Vec<VectorSearchResult> = hnsw_results
265                    .into_iter()
266                    .map(|(key, distance)| VectorSearchResult { key, distance })
267                    .collect();
268                let bytes: u64 = results
269                    .iter()
270                    .map(|r| r.key.len() as u64 + query.data.len() as u64)
271                    .sum();
272                let stats = QueryStats {
273                    segments_scanned: 0,
274                    bytes_scanned: bytes,
275                    items_examined: results.len() as u64,
276                };
277                return Ok((results, stats));
278            }
279        }
280
281        let vec_ns = vector_namespace(ns);
282        let all = self.prefix(&vec_ns, b"")?;
283        let items_examined = all.len() as u64;
284        let bytes_scanned: u64 = all
285            .iter()
286            .map(|(k, v)| k.len() as u64 + v.len() as u64)
287            .sum();
288        let results = crate::vector::search::vector_search(self, ns, query, k, metric)?;
289        let stats = QueryStats {
290            segments_scanned: 1,
291            bytes_scanned,
292            items_examined,
293        };
294        Ok((results, stats))
295    }
296
297    /// Fetch one page of decoded vector records for cooperative async flat scans.
298    ///
299    /// Designed for async callers (e.g. `edgestore-tokio`) that want to iterate
300    /// through a vector namespace without holding the engine lock for the full
301    /// flat-scan duration. Takes `&self` (read lock only) — no HNSW mutation.
302    ///
303    /// Pass `None` as `cursor` to start from the beginning. On each call the
304    /// returned `next_key` (if `Some`) is the cursor for the next page.
305    pub fn vector_page(
306        &self,
307        ns: &[u8],
308        cursor: Option<&[u8]>,
309        page_size: usize,
310    ) -> Result<VectorPage, EdgestoreError> {
311        crate::vector::search::vector_page(self, ns, cursor, page_size)
312    }
313}
314
315impl VectorEngine for Engine {
316    fn vector_put(
317        &mut self,
318        ns: &[u8],
319        key: &[u8],
320        dims: u16,
321        dtype: Dtype,
322        data: &[u8],
323    ) -> Result<Lsn, EdgestoreError> {
324        let expected = dims as usize * dtype.element_size();
325        if data.len() != expected {
326            return Err(EdgestoreError::DimensionMismatch {
327                expected,
328                actual: data.len(),
329            });
330        }
331
332        let record = VectorRecord {
333            dims,
334            dtype,
335            data: data.to_vec(),
336        };
337        let encoded = encode_vector_record(&record)?;
338        self.put(&vector_namespace(ns), key, &encoded)
339    }
340
341    fn vector_get(&self, ns: &[u8], key: &[u8]) -> Result<Option<VectorRecord>, EdgestoreError> {
342        match self.get(&vector_namespace(ns), key)? {
343            Some(bytes) => {
344                let record = decode_vector_record(&bytes)
345                    .map_err(|e| EdgestoreError::CorruptData(format!("decode vector: {}", e)))?;
346                Ok(Some(record))
347            }
348            None => Ok(None),
349        }
350    }
351
352    fn vector_delete(&mut self, ns: &[u8], key: &[u8]) -> Result<Lsn, EdgestoreError> {
353        self.delete(&vector_namespace(ns), key)
354    }
355}