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 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 let all = self.prefix(&vec_ns, b"")?;
24 if all.is_empty() {
25 return Ok(());
26 }
27
28 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; let mut index = HnswIndex::new(dims, dtype, metric).with_params(16, 100);
36
37 for (key, val) in &all {
38 let rec = decode_vector_record(val)?;
40 index.insert(key.clone(), rec.data)?;
41 }
42
43 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 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 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 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 pub(crate) fn get_vector_index(
93 &self,
94 ns: &[u8],
95 ) -> Result<Option<Arc<HnswIndex>>, EdgestoreError> {
96 {
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 } 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 }
116 }
117
118 let mut indices = self.vector_indices.write().unwrap();
120
121 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 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 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 pub fn vector_search(
227 &self,
228 ns: &[u8],
229 query: &VectorRecord,
230 k: usize,
231 metric: Metric,
232 ) -> Result<Vec<VectorSearchResult>, EdgestoreError> {
233 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 crate::vector::search::vector_search(self, ns, query, k, metric)
246 }
247
248 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 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 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}