π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: API v2 batch β bulk search core, stored-key search, purge, FFI surface rework
laurenspriem499f0265e6dc
diff --git a/rust/bindings/frb/photos/src/api/vecdb_api.rs b/rust/bindings/frb/photos/src/api/vecdb_api.rsindex 33c0927978..f90f544643 100644--- a/rust/bindings/frb/photos/src/api/vecdb_api.rs+++ b/rust/bindings/frb/photos/src/api/vecdb_api.rs@@ -32,6 +32,7 @@ impl From<vecdb::VecDbError> for RustVecDbError {vecdb::VecDbError::DimensionMismatch { .. } => Self::DimensionMismatch { message },vecdb::VecDbError::InvalidDimensions(_) => Self::InvalidDimensions { message },vecdb::VecDbError::UnboundedSearch => Self::UnboundedSearch { message },+ vecdb::VecDbError::LengthMismatch { .. } => Self::LengthMismatch { message },}}}@@ -46,16 +47,17 @@ pub struct VecDbMatch {pub struct VecDbKeyMatches {pub key: String,pub matches: Vec<VecDbMatch>,+ pub truncated: bool,}#[derive(Clone, Debug)]pub struct VecDbStats {- pub live_count: usize,- pub dead_count: usize,- pub dims: usize,+ pub live_count: u32,+ pub dead_count: u32,+ pub dims: u32,pub log_bytes: u64,- pub records_since_snapshot: usize,- pub approximate_memory_bytes: usize,+ pub records_since_snapshot: u32,+ pub approximate_memory_bytes: u64,}fn to_api_match(entry: vecdb::Match) -> VecDbMatch {@@ -65,49 +67,56 @@ fn to_api_match(entry: vecdb::Match) -> VecDbMatch {}}+fn to_api_matches(matches: Vec<vecdb::Match>) -> Vec<VecDbMatch> {+ matches.into_iter().map(to_api_match).collect()+}++fn distance_cut(matches: &mut Vec<VecDbMatch>, max_distance: f32) {+ let keep = matches.partition_point(|entry| entry.distance <= max_distance);+ matches.truncate(keep);+}++fn valid_distance(distance: f32) -> bool {+ distance.is_finite() && distance >= 0.0+}++pub fn delete_vec_db_files(file_path: String) -> Result<(), RustVecDbError> {+ Ok(vecdb::VecDb::purge(Path::new(&file_path))?)+}+#[frb(opaque)]pub struct VecDb {inner: vecdb::VecDb,}impl VecDb {- #[frb(sync)]- pub fn new(file_path: String, dimensions: usize) -> Result<Self, RustVecDbError> {+ pub fn new(file_path: String, dimensions: u32) -> Result<Self, RustVecDbError> {Ok(Self {- inner: vecdb::VecDb::open(Path::new(&file_path), dimensions)?,+ inner: vecdb::VecDb::open(Path::new(&file_path), dimensions as usize)?,})}- pub fn open_read_only(file_path: String, dimensions: usize) -> Result<Self, RustVecDbError> {+ pub fn open_read_only(file_path: String, dimensions: u32) -> Result<Self, RustVecDbError> {Ok(Self {- inner: vecdb::VecDb::open_read_only(Path::new(&file_path), dimensions)?,+ inner: vecdb::VecDb::open_read_only(Path::new(&file_path), dimensions as usize)?,})}pub fn search(&self,query: Vec<f32>,- limit: Option<usize>,+ limit: Option<u32>,max_distance: Option<f32>,exact: bool,allowed_keys: Option<Vec<String>>,) -> Result<Vec<VecDbMatch>, RustVecDbError> {let params = vecdb::SearchParams {- limit,+ limit: limit.map(|value| value as usize),max_distance,exact,allowed_keys,};- self.run_search(&query, ¶ms)- }-- fn run_search(- &self,- query: &[f32],- params: &vecdb::SearchParams,- ) -> Result<Vec<VecDbMatch>, RustVecDbError> {- let matches = self.inner.search(query, params)?;- Ok(matches.into_iter().map(to_api_match).collect())+ Ok(to_api_matches(self.inner.search(&query, ¶ms)?))}pub fn add_vector(&self, key: String, vector: Vec<f32>) -> Result<(), RustVecDbError> {@@ -119,139 +128,111 @@ impl VecDb {keys: Vec<String>,vectors: Vec<Vec<f32>>,) -> Result<(), RustVecDbError> {- if keys.len() != vectors.len() {- return Err(RustVecDbError::LengthMismatch {- message: format!(- "keys length {} does not match vectors length {}",- keys.len(),- vectors.len()- ),- });- }- let entries: Vec<(String, Vec<f32>)> = keys.into_iter().zip(vectors).collect();- Ok(self.inner.bulk_add(&entries)?)+ Ok(self.inner.bulk_add(&keys, &vectors)?)}- pub fn search_vectors(+ pub fn approx_search_vectors_within_similarity(&self,query: Vec<f32>,- count: usize,- exact: bool,+ minimum_similarity: f32,) -> Result<Vec<VecDbMatch>, RustVecDbError> {- self.search(query, Some(count), None, exact, None)+ self.search(query, None, Some(1.0 - minimum_similarity), false, None)}- pub fn bulk_search_vectors(+ pub fn bulk_search_within_similarity(&self,queries: Vec<Vec<f32>>,- count: usize,+ minimum_similarities: Vec<f32>,+ limit: Option<u32>,exact: bool,) -> Result<Vec<Vec<VecDbMatch>>, RustVecDbError> {+ if queries.len() != minimum_similarities.len() {+ return Err(RustVecDbError::LengthMismatch {+ message: format!(+ "queries length {} does not match similarities length {}",+ queries.len(),+ minimum_similarities.len()+ ),+ });+ }+ let cuts: Vec<f32> = minimum_similarities+ .iter()+ .map(|similarity| 1.0 - similarity)+ .collect();+ let widest = cuts+ .iter()+ .copied()+ .filter(|cut| valid_distance(*cut))+ .fold(f32::NEG_INFINITY, f32::max);let params = vecdb::SearchParams {- limit: Some(count),- max_distance: None,+ limit: limit.map(|value| value as usize),+ max_distance: Some(widest),exact,allowed_keys: None,};- queries- .iter()- .map(|query| self.run_search(query, ¶ms))- .collect()- }-- pub fn search_vectors_within_distance(- &self,- query: Vec<f32>,- max_distance: f32,- exact: bool,- ) -> Result<Vec<VecDbMatch>, RustVecDbError> {- self.search(query, None, Some(max_distance), exact, None)- }-- pub fn approx_search_vectors_within_similarity(- &self,- query: Vec<f32>,- minimum_similarity: f32,- ) -> Result<Vec<VecDbMatch>, RustVecDbError> {- self.search(query, None, Some(1.0 - minimum_similarity), false, None)- }-- pub fn approx_filtered_search_vectors_within_distance(- &self,- query: Vec<f32>,- allowed_keys: Vec<String>,- count: usize,- max_distance: f32,- ) -> Result<Vec<VecDbMatch>, RustVecDbError> {- self.search(- query,- Some(count),- Some(max_distance),- false,- Some(allowed_keys),- )+ let results = self.inner.bulk_search(&queries, ¶ms)?;+ Ok(results+ .into_iter()+ .zip(cuts)+ .map(|(matches, cut)| {+ if !valid_distance(cut) {+ return Vec::new();+ }+ let mut matches = to_api_matches(matches);+ distance_cut(&mut matches, cut);+ matches+ })+ .collect())}pub fn bulk_approx_filtered_search_vectors_within_distance(&self,queries: Vec<Vec<f32>>,allowed_keys: Vec<String>,- count: usize,+ count: u32,max_distance: f32,) -> Result<Vec<Vec<VecDbMatch>>, RustVecDbError> {let params = vecdb::SearchParams {- limit: Some(count),+ limit: Some(count as usize),max_distance: Some(max_distance),exact: false,allowed_keys: Some(allowed_keys),};- queries- .iter()- .map(|query| self.run_search(query, ¶ms))- .collect()+ let results = self.inner.bulk_search(&queries, ¶ms)?;+ Ok(results.into_iter().map(to_api_matches).collect())}pub fn bulk_search_keys(&self,potential_keys: Vec<String>,- count: usize,+ count: u32,+ max_distance: Option<f32>,exact: bool,+ restrict_to_input: bool,) -> Result<Vec<VecDbKeyMatches>, RustVecDbError> {- let params = vecdb::SearchParams {- limit: Some(count),- max_distance: None,+ let results = self.inner.bulk_search_stored(+ &potential_keys,+ count as usize,+ max_distance,exact,- allowed_keys: None,- };- let mut results = Vec::new();- for key in potential_keys {- let Some(vector) = self.inner.get(&key) else {- continue;- };- let matches = self.run_search(&vector, ¶ms)?;- results.push(VecDbKeyMatches { key, matches });- }- Ok(results)- }-- pub fn contains_vector(&self, key: String) -> bool {- self.inner.contains(&key)- }-- pub fn get_vector(&self, key: String) -> Option<Vec<f32>> {- self.inner.get(&key)+ restrict_to_input,+ )?;+ Ok(results+ .into_iter()+ .map(|entry| VecDbKeyMatches {+ key: entry.key,+ matches: to_api_matches(entry.matches),+ truncated: entry.truncated,+ })+ .collect())}pub fn bulk_get_vectors(&self, keys: Vec<String>) -> Vec<Option<Vec<f32>>> {keys.iter().map(|key| self.inner.get(key)).collect()}- pub fn remove_vector(&self, key: String) -> Result<usize, RustVecDbError> {- Ok(usize::from(self.inner.remove(&key)?))- }-- pub fn bulk_remove_vectors(&self, keys: Vec<String>) -> Result<usize, RustVecDbError> {- Ok(self.inner.bulk_remove(&keys)?)+ pub fn bulk_remove_vectors(&self, keys: Vec<String>) -> Result<u32, RustVecDbError> {+ Ok(self.inner.bulk_remove(&keys)? as u32)}pub fn flush(&self) -> Result<(), RustVecDbError> {@@ -266,33 +247,16 @@ impl VecDb {Ok(self.inner.delete()?)}- pub fn get_index_stats(&self) -> VecDbStats {- match self.inner.stats() {- Ok(stats) => VecDbStats {- live_count: stats.live_count,- dead_count: stats.dead_count,- dims: stats.dims,- log_bytes: stats.log_bytes,- records_since_snapshot: stats.records_since_snapshot,- approximate_memory_bytes: stats.approximate_memory_bytes,- },- Err(_) => VecDbStats {- live_count: 0,- dead_count: 0,- dims: 0,- log_bytes: 0,- records_since_snapshot: 0,- approximate_memory_bytes: 0,- },- }- }-- pub fn len(&self) -> usize {- self.inner.len()- }-- pub fn is_empty(&self) -> bool {- self.inner.is_empty()+ pub fn get_index_stats(&self) -> Result<VecDbStats, RustVecDbError> {+ let stats = self.inner.stats()?;+ Ok(VecDbStats {+ live_count: stats.live_count as u32,+ dead_count: stats.dead_count as u32,+ dims: stats.dims as u32,+ log_bytes: stats.log_bytes,+ records_since_snapshot: stats.records_since_snapshot as u32,+ approximate_memory_bytes: stats.approximate_memory_bytes as u64,+ })}}@@ -303,7 +267,7 @@ mod tests {use super::*;- const DIMS: usize = 8;+ const DIMS: u32 = 8;static TEST_DIR_COUNTER: AtomicU32 = AtomicU32::new(0);@@ -333,7 +297,7 @@ mod tests {}fn basis(axis: usize) -> Vec<f32> {- let mut vector = vec![0.0; DIMS];+ let mut vector = vec![0.0; DIMS as usize];vector[axis] = 1.0;vector}@@ -349,63 +313,49 @@ mod tests {db.add_vector(key("a"), basis(0)).unwrap();db.bulk_add_vectors(vec![key("b"), key("c")], vec![basis(1), basis(2)]).unwrap();- assert!(db.contains_vector(key("a")));- assert!(!db.contains_vector(key("missing")));- assert_eq!(db.get_vector(key("b")).unwrap(), basis(1));- assert!(db.get_vector(key("missing")).is_none());assert_eq!(db.bulk_get_vectors(vec![key("c"), key("missing")]),vec![Some(basis(2)), None]);- let matches = db.search_vectors(basis(0), 2, true).unwrap();+ let matches = db.search(basis(0), Some(2), None, true, None).unwrap();assert_eq!(matches[0].key, "a");assert!(matches[0].distance.abs() < 1.0e-6);- let bulk = db- .bulk_search_vectors(vec![basis(1), basis(2)], 1, false)- .unwrap();- assert_eq!(bulk.len(), 2);- assert_eq!(bulk[0][0].key, "b");- assert_eq!(bulk[1][0].key, "c");+ let within = db.search(basis(0), None, Some(0.5), true, None).unwrap();+ assert_eq!(within.len(), 1);+ assert_eq!(within[0].key, "a");let filtered = db- .approx_filtered_search_vectors_within_distance(+ .search(basis(0),- vec![key("b"), key("c")],- 3,- 2.0,+ Some(3),+ Some(2.0),+ false,+ Some(vec![key("b"), key("c")]),).unwrap();assert!(filtered.iter().all(|found| found.key != "a"));assert_eq!(filtered.len(), 2);- let within = db- .search_vectors_within_distance(basis(0), 0.5, true)- .unwrap();- assert_eq!(within.len(), 1);- assert_eq!(within[0].key, "a");- let stats = db.get_index_stats();+ let stats = db.get_index_stats().unwrap();assert_eq!(stats.live_count, 3);assert_eq!(stats.dead_count, 0);assert_eq!(stats.dims, DIMS);assert!(stats.log_bytes > 32);assert!(stats.approximate_memory_bytes > 0);- assert_eq!(db.len(), 3);- assert!(!db.is_empty());db.flush().unwrap();- assert_eq!(db.get_index_stats().records_since_snapshot, 0);+ assert_eq!(db.get_index_stats().unwrap().records_since_snapshot, 0);let read_only = VecDb::open_read_only(dir.db_path(), DIMS).unwrap();- assert_eq!(read_only.len(), 3);+ assert_eq!(read_only.get_index_stats().unwrap().live_count, 3);assert!(matches!(read_only.add_vector(key("x"), basis(3)),Err(RustVecDbError::ReadOnly { .. })));- assert_eq!(db.remove_vector(key("a")).unwrap(), 1);- assert_eq!(db.remove_vector(key("a")).unwrap(), 0);assert_eq!(- db.bulk_remove_vectors(vec![key("b"), key("nope")]).unwrap(),- 1+ db.bulk_remove_vectors(vec![key("a"), key("b"), key("nope")])+ .unwrap(),+ 2);- assert_eq!(db.len(), 1);+ assert_eq!(db.get_index_stats().unwrap().live_count, 1);db.reset_index().unwrap();- assert!(db.is_empty());+ assert_eq!(db.get_index_stats().unwrap().live_count, 0);db.add_vector(key("again"), basis(3)).unwrap();db.delete_index().unwrap();assert!(!PathBuf::from(dir.db_path()).exists());@@ -419,7 +369,7 @@ mod tests {.bulk_add_vectors(vec![key("a")], vec![basis(0), basis(1)]).unwrap_err();assert!(matches!(error, RustVecDbError::LengthMismatch { .. }));- assert!(db.is_empty());+ assert_eq!(db.get_index_stats().unwrap().live_count, 0);}#[test]@@ -446,6 +396,72 @@ mod tests {}}+ #[test]+ fn bulk_search_within_similarity_honors_per_query_thresholds() {+ let dir = TestDir::create();+ let db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.bulk_add_vectors(+ vec![key("a"), key("b"), key("c")],+ vec![basis(0), basis(1), basis(2)],+ )+ .unwrap();+ let queries = vec![basis(0), basis(0), basis(1)];+ let results = db+ .bulk_search_within_similarity(queries.clone(), vec![0.5, -1.0, 0.5], None, true)+ .unwrap();+ assert_eq!(results.len(), 3);+ assert_eq!(results[0].len(), 1);+ assert_eq!(results[0][0].key, "a");+ assert_eq!(results[1].len(), 3);+ assert_eq!(results[2].len(), 1);+ assert_eq!(results[2][0].key, "b");+ let limited = db+ .bulk_search_within_similarity(queries.clone(), vec![-1.0, -1.0, -1.0], Some(2), false)+ .unwrap();+ assert!(limited.iter().all(|matches| matches.len() == 2));+ let mixed = vec![0.5, -1.0, 0.9];+ for exact in [true, false] {+ let bulk = db+ .bulk_search_within_similarity(queries.clone(), mixed.clone(), Some(2), exact)+ .unwrap();+ for ((query, similarity), matches) in queries.iter().zip(&mixed).zip(&bulk) {+ let direct = db+ .search(query.clone(), Some(2), Some(1.0 - similarity), exact, None)+ .unwrap();+ assert_eq!(matches.len(), direct.len());+ for (found, expected) in matches.iter().zip(&direct) {+ assert_eq!(found.key, expected.key);+ assert_eq!(found.distance, expected.distance);+ }+ }+ }+ assert!(matches!(+ db.bulk_search_within_similarity(queries.clone(), vec![0.5], None, false),+ Err(RustVecDbError::LengthMismatch { .. })+ ));+ let degenerate = db+ .bulk_search_within_similarity(+ queries.clone(),+ vec![f32::NAN, 1.5, -1.0],+ Some(3),+ true,+ )+ .unwrap();+ assert!(degenerate[0].is_empty());+ assert!(degenerate[1].is_empty());+ assert_eq!(degenerate[2].len(), 3);+ let all_degenerate = db+ .bulk_search_within_similarity(+ queries,+ vec![f32::NAN, f32::INFINITY, 3.0],+ Some(3),+ false,+ )+ .unwrap();+ assert_eq!(all_degenerate.len(), 3);+ assert!(all_degenerate.iter().all(Vec::is_empty));+ }+#[test]fn bulk_filtered_search_stays_query_aligned() {let dir = TestDir::create();@@ -501,20 +517,66 @@ mod tests {}#[test]- fn bulk_search_keys_includes_self_match_and_skips_absent() {+ fn bulk_search_keys_excludes_self_and_reports_truncation() {let dir = TestDir::create();let db = VecDb::new(dir.db_path(), DIMS).unwrap();- db.bulk_add_vectors(vec![key("a"), key("b")], vec![basis(0), basis(1)])- .unwrap();+ db.bulk_add_vectors(+ vec![key("a"), key("b"), key("c")],+ vec![basis(0), basis(1), basis(2)],+ )+ .unwrap();let results = db- .bulk_search_keys(vec![key("missing"), key("b"), key("a")], 2, true)+ .bulk_search_keys(+ vec![key("missing"), key("b"), key("a")],+ 2,+ None,+ true,+ false,+ ).unwrap();assert_eq!(results.len(), 2);assert_eq!(results[0].key, "b");- assert_eq!(results[0].matches[0].key, "b");- assert!(results[0].matches[0].distance.abs() < 1.0e-6);assert_eq!(results[0].matches.len(), 2);+ assert!(results[0].matches.iter().all(|found| found.key != "b"));+ assert!(results[0].truncated);assert_eq!(results[1].key, "a");- assert_eq!(results[1].matches[0].key, "a");+ assert!(results[1].matches.iter().all(|found| found.key != "a"));+ let restricted = db+ .bulk_search_keys(vec![key("a"), key("b")], 5, None, true, true)+ .unwrap();+ for entry in &restricted {+ assert_eq!(entry.matches.len(), 1);+ assert!(!entry.truncated);+ }+ assert_eq!(restricted[0].matches[0].key, "b");+ assert_eq!(restricted[1].matches[0].key, "a");+ let cut = db+ .bulk_search_keys(vec![key("a")], 2, Some(0.5), false, false)+ .unwrap();+ assert!(cut[0].matches.is_empty());+ assert!(cut[0].truncated);+ }++ #[test]+ fn delete_vec_db_files_purges_with_and_without_live_instances() {+ let dir = TestDir::create();+ let db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.add_vector(key("a"), basis(0)).unwrap();+ db.flush().unwrap();+ delete_vec_db_files(dir.db_path()).unwrap();+ assert!(!PathBuf::from(dir.db_path()).exists());+ assert!(!PathBuf::from(format!("{}.graph", dir.db_path())).exists());+ assert!(!PathBuf::from(format!("{}.lock", dir.db_path())).exists());+ assert!(matches!(+ db.get_index_stats(),+ Err(RustVecDbError::Closed { .. })+ ));+ let reopened = VecDb::new(dir.db_path(), DIMS).unwrap();+ assert_eq!(reopened.get_index_stats().unwrap().live_count, 0);+ reopened.add_vector(key("b"), basis(1)).unwrap();+ drop(reopened);+ delete_vec_db_files(dir.db_path()).unwrap();+ assert!(!PathBuf::from(dir.db_path()).exists());+ delete_vec_db_files(dir.db_path()).unwrap();}}diff --git a/rust/crates/ml/examples/vecdb_bench.rs b/rust/crates/ml/examples/vecdb_bench.rsindex aa8909740d..97e919ce82 100644--- a/rust/crates/ml/examples/vecdb_bench.rs+++ b/rust/crates/ml/examples/vecdb_bench.rs@@ -318,9 +318,13 @@ fn ingest_phase(db: &mut VecDb, data: &BenchData, scale: usize) -> IngestTimingslet single_total = started.elapsed();let rest = &data.entries[single_count..];eprintln!("[scale {scale}] vecdb bulk adds");+ let batches: Vec<(Vec<String>, Vec<Vec<f32>>)> = rest+ .chunks(BULK_BATCH_SIZE)+ .map(|batch| batch.iter().cloned().unzip())+ .collect();let started = Instant::now();- for batch in rest.chunks(BULK_BATCH_SIZE) {- db.bulk_add(batch).expect("vecdb bulk add");+ for (keys, vectors) in &batches {+ db.bulk_add(keys, vectors).expect("vecdb bulk add");}let bulk_total = started.elapsed();db.add("bench-probe", &data.probe).expect("vecdb probe add");diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rsindex da5b461357..53190fd980 100644--- a/rust/crates/ml/src/vecdb/graph.rs+++ b/rust/crates/ml/src/vecdb/graph.rs@@ -464,6 +464,17 @@ pub(crate) fn search(query: &[f32x8],params: &SearchParams,allowed_slots: Option<&HashSet<u32>>,+) -> Vec<Match> {+ search_excluding(graph, arena, query, params, allowed_slots, None)+}++pub(crate) fn search_excluding(+ graph: &Graph,+ arena: &VectorArena,+ query: &[f32x8],+ params: &SearchParams,+ allowed_slots: Option<&HashSet<u32>>,+ banned_slot: Option<u32>,) -> Vec<Match> {debug_assert!(params.limit.is_some() || params.max_distance.is_some());if let Some(max_distance) = params.max_distance {@@ -477,15 +488,15 @@ pub(crate) fn search(return Vec::new();}if params.exact {- return brute_force(arena, query, params, allowed_slots);+ return brute_force(arena, query, params, allowed_slots, banned_slot);}if let Some(allowed) = allowed_slots&& allowed.len() <= small_filter_cap(params.limit){- return brute_force(arena, query, params, allowed_slots);+ return brute_force(arena, query, params, allowed_slots, banned_slot);}if graph.entry_point.is_none() {- return brute_force(arena, query, params, allowed_slots);+ return brute_force(arena, query, params, allowed_slots, banned_slot);}let context = QueryContext {graph,@@ -493,11 +504,18 @@ pub(crate) fn search(query,};match params.limit {- Some(limit) => approx_limited(&context, limit, params.max_distance, allowed_slots),+ Some(limit) => approx_limited(+ &context,+ limit,+ params.max_distance,+ allowed_slots,+ banned_slot,+ ),None => approx_threshold(&context,params.max_distance.unwrap_or(f32::MAX),allowed_slots,+ banned_slot,),}}@@ -524,8 +542,13 @@ fn result_bound(arena: &VectorArena, allowed: Option<&HashSet<u32>>) -> usize {fn admission<'a>(arena: &'a VectorArena,allowed: Option<&'a HashSet<u32>>,+ banned: Option<u32>,) -> impl Fn(u32) -> bool + 'a {- move |slot| arena.is_alive(slot) && allowed.is_none_or(|set| set.contains(&slot))+ move |slot| {+ banned != Some(slot)+ && arena.is_alive(slot)+ && allowed.is_none_or(|set| set.contains(&slot))+ }}fn approx_limited(@@ -533,13 +556,14 @@ fn approx_limited(limit: usize,max_distance: Option<f32>,allowed: Option<&HashSet<u32>>,+ banned: Option<u32>,) -> Vec<Match> {let bound = result_bound(context.arena, allowed);let ef = limit.saturating_mul(EF_SEARCH_LIMIT_FACTOR).max(EF_SEARCH_FLOOR).min(bound);- let admit = admission(context.arena, allowed);+ let admit = admission(context.arena, allowed, banned);let scored = context.top_scored(ef, &admit);to_matches(context.arena, scored, Some(limit), max_distance)}@@ -548,9 +572,10 @@ fn approx_threshold(context: &QueryContext<'_>,max_distance: f32,allowed: Option<&HashSet<u32>>,+ banned: Option<u32>,) -> Vec<Match> {let bound = result_bound(context.arena, allowed);- let admit = admission(context.arena, allowed);+ let admit = admission(context.arena, allowed, banned);let mut previous = 0usize;for step in THRESHOLD_STEP_COUNTS.into_iter()@@ -579,11 +604,12 @@ fn brute_force(query: &[f32x8],params: &SearchParams,allowed: Option<&HashSet<u32>>,+ banned: Option<u32>,) -> Vec<Match> {let mut top: BinaryHeap<Scored> = BinaryHeap::new();let mut all: Vec<Scored> = Vec::new();let mut consider = |slot: u32| {- if !arena.is_alive(slot) {+ if banned == Some(slot) || !arena.is_alive(slot) {return;}let distance = arena.distance_to_query(query, slot);@@ -1034,6 +1060,103 @@ mod tests {assert_eq!(keys(&without_graph), ["only"]);}+ #[test]+ fn banned_entry_point_is_excluded_yet_still_routes_traversal() {+ let (arena, graph) = (&FIXTURE.0, &FIXTURE.1);+ let entry = graph.entry_point().unwrap();+ let entry_key = arena.key_of_slot(entry).unwrap();+ let query = arena.vector_lanes(entry).to_vec();+ let reference = reference_ranking(arena, &query, None);+ assert_eq!(reference[0].1, entry);+ for exact in [true, false] {+ let found = search_excluding(+ graph,+ arena,+ &query,+ ¶ms(Some(10), None, exact),+ None,+ Some(entry),+ );+ assert_eq!(found.len(), 10);+ assert_sorted(&found);+ assert!(found.iter().all(|hit| hit.key != entry_key));+ if exact {+ let expected: Vec<&str> = reference[1..11]+ .iter()+ .map(|&(_, slot)| arena.key_of_slot(slot).unwrap())+ .collect();+ assert_eq!(keys(&found), expected);+ }+ }+ let everything = search_excluding(+ graph,+ arena,+ &query,+ ¶ms(None, Some(2.5), false),+ None,+ Some(entry),+ );+ assert_eq!(everything.len(), FIXTURE_COUNT - 1);+ assert!(everything.iter().all(|hit| hit.key != entry_key));+ let large_filter: HashSet<u32> = (0..1200).chain([entry]).collect();+ assert!(large_filter.len() > small_filter_cap(Some(10)));+ let filtered = search_excluding(+ graph,+ arena,+ &query,+ ¶ms(Some(10), None, false),+ Some(&large_filter),+ Some(entry),+ );+ assert_eq!(filtered.len(), 10);+ assert!(filtered.iter().all(|hit| hit.key != entry_key));+ let small_filter: HashSet<u32> = reference[..12].iter().map(|&(_, slot)| slot).collect();+ let brute = search_excluding(+ graph,+ arena,+ &query,+ ¶ms(Some(12), None, false),+ Some(&small_filter),+ Some(entry),+ );+ let expected: Vec<&str> = reference[1..12]+ .iter()+ .map(|&(_, slot)| arena.key_of_slot(slot).unwrap())+ .collect();+ assert_eq!(keys(&brute), expected);+ }++ #[test]+ fn banned_only_node_yields_empty_in_every_mode() {+ let mut arena = VectorArena::new(8).unwrap();+ arena.upsert("only", &axis_vector(8, 0)).unwrap();+ let graph = Graph::rebuild(&arena);+ let query = arena.vector_lanes(0).to_vec();+ let allowed: HashSet<u32> = [0].into_iter().collect();+ for exact in [true, false] {+ for filter in [None, Some(&allowed)] {+ let by_limit = search_excluding(+ &graph,+ &arena,+ &query,+ ¶ms(Some(5), None, exact),+ filter,+ Some(0),+ );+ assert!(by_limit.is_empty());+ let by_threshold = search_excluding(+ &graph,+ &arena,+ &query,+ ¶ms(None, Some(2.5), exact),+ filter,+ Some(0),+ );+ assert!(by_threshold.is_empty());+ }+ }+ }+#[test]fn all_dead_index_returns_empty() {let mut arena = build_arena(5, 8, 0x0B00_0000);diff --git a/rust/crates/ml/src/vecdb/mod.rs b/rust/crates/ml/src/vecdb/mod.rsindex 2684d684e2..5102b6f145 100644--- a/rust/crates/ml/src/vecdb/mod.rs+++ b/rust/crates/ml/src/vecdb/mod.rs@@ -27,6 +27,13 @@ pub struct Match {pub distance: f32,}+#[derive(Debug, Clone, PartialEq)]+pub struct KeyMatches {+ pub key: String,+ pub matches: Vec<Match>,+ pub truncated: bool,+}+#[derive(Debug, Error)]pub enum VecDbError {#[error("{}: {source}", path.display())]@@ -53,6 +60,8 @@ pub enum VecDbError {InvalidDimensions(usize),#[error("search requires a limit or a max distance")]UnboundedSearch,+ #[error("length mismatch: {keys} keys, {vectors} vectors")]+ LengthMismatch { keys: usize, vectors: usize },}impl VecDbError {diff --git a/rust/crates/ml/src/vecdb/store.rs b/rust/crates/ml/src/vecdb/store.rsindex 69c93206ff..743285db58 100644--- a/rust/crates/ml/src/vecdb/store.rs+++ b/rust/crates/ml/src/vecdb/store.rs@@ -9,14 +9,14 @@ use std::sync::{use std::time::{Duration, Instant};use super::arena::{UpsertOutcome, VECTORS_PER_CHUNK, VectorArena};-use super::graph::{Graph, search as graph_search};+use super::graph::{Graph, search as graph_search, search_excluding};use super::lock::{WriterLock, lock_path};use super::log::{HEADER_LEN, Log, LogEntry, LogRecord, remove_if_present, remove_stale_temp_sibling,sync_parent_dir,};use super::snapshot::{load_snapshot, remove_snapshot, snapshot_path, write_snapshot};-use super::{Match, SearchParams, VecDbError};+use super::{KeyMatches, Match, SearchParams, VecDbError};const SNAPSHOT_HARD_CAP: usize = 5000;const SNAPSHOT_QUIET_THRESHOLD: usize = 1000;@@ -238,25 +238,32 @@ impl VecDb {apply_policy(&self.shared, &mut half, 1, now)}- pub fn bulk_add(&self, entries: &[(String, Vec<f32>)]) -> Result<(), VecDbError> {+ pub fn bulk_add(&self, keys: &[String], vectors: &[Vec<f32>]) -> Result<(), VecDbError> {+ if keys.len() != vectors.len() {+ return Err(VecDbError::LengthMismatch {+ keys: keys.len(),+ vectors: vectors.len(),+ });+ }let now = Instant::now();let mut half = self.writable_half()?;let state = active_state(&mut half)?;- if entries.is_empty() {+ if keys.is_empty() {return Ok(());}- for (key, vector) in entries {+ for (key, vector) in keys.iter().zip(vectors) {ensure_finite(key, vector)?;}- let records: Vec<LogEntry<'_>> = entries+ let records: Vec<LogEntry<'_>> = keys.iter()+ .zip(vectors).map(|(key, vector)| LogEntry::Add { key, vector }).collect();state.log.append(&records)?;- for (key, vector) in entries {+ for (key, vector) in keys.iter().zip(vectors) {apply_add(&self.shared, key, vector)?;}- apply_policy(&self.shared, &mut half, entries.len(), now)+ apply_policy(&self.shared, &mut half, keys.len(), now)}pub fn remove(&self, key: &str) -> Result<bool, VecDbError> {@@ -315,28 +322,85 @@ impl VecDb {pub fn search(&self, query: &[f32], params: &SearchParams) -> Result<Vec<Match>, VecDbError> {self.shared.ensure_open()?;- if params.limit.is_none() && params.max_distance.is_none() {- return Err(VecDbError::UnboundedSearch);- }- if let Some(max_distance) = params.max_distance- && (!max_distance.is_finite() || max_distance < 0.0)- {+ if degenerate_distance_cut(params)? {return Ok(Vec::new());}let st = self.shared.state_read();- let packed = st.arena.pack_query(query)?;- let allowed_slots: Option<HashSet<u32>> = params.allowed_keys.as_ref().map(|keys| {- keys.iter()- .filter_map(|key| st.arena.slot_of_key(key))- .collect()- });- Ok(graph_search(- &st.graph,- &st.arena,- &packed,- params,- allowed_slots.as_ref(),- ))+ let allowed_slots = resolve_allowed_slots(&st, params.allowed_keys.as_deref());+ search_in_state(&st, query, params, allowed_slots.as_ref())+ }++ pub fn bulk_search(+ &self,+ queries: &[Vec<f32>],+ params: &SearchParams,+ ) -> Result<Vec<Vec<Match>>, VecDbError> {+ self.shared.ensure_open()?;+ if degenerate_distance_cut(params)? {+ return Ok(queries.iter().map(|_| Vec::new()).collect());+ }+ let st = self.shared.state_read();+ let allowed_slots = resolve_allowed_slots(&st, params.allowed_keys.as_deref());+ queries+ .iter()+ .map(|query| search_in_state(&st, query, params, allowed_slots.as_ref()))+ .collect()+ }++ pub fn bulk_search_stored(+ &self,+ keys: &[String],+ count: usize,+ max_distance: Option<f32>,+ exact: bool,+ restrict_to_input: bool,+ ) -> Result<Vec<KeyMatches>, VecDbError> {+ self.shared.ensure_open()?;+ let st = self.shared.state_read();+ let resolved: Vec<(&String, u32)> = keys+ .iter()+ .filter_map(|key| st.arena.slot_of_key(key).map(|slot| (key, slot)))+ .collect();+ let degenerate =+ max_distance.is_some_and(|distance| !distance.is_finite() || distance < 0.0);+ let allowed_slots: Option<HashSet<u32>> =+ restrict_to_input.then(|| resolved.iter().map(|(_, slot)| *slot).collect());+ let params = SearchParams {+ limit: Some(count),+ max_distance: None,+ exact,+ allowed_keys: None,+ };+ let mut results = Vec::with_capacity(resolved.len());+ for (key, slot) in resolved {+ if degenerate {+ results.push(KeyMatches {+ key: key.clone(),+ matches: Vec::new(),+ truncated: false,+ });+ continue;+ }+ let mut matches = search_excluding(+ &st.graph,+ &st.arena,+ st.arena.vector_lanes(slot),+ ¶ms,+ allowed_slots.as_ref(),+ Some(slot),+ );+ let truncated = matches.len() >= count;+ if let Some(cap) = max_distance {+ let keep = matches.partition_point(|entry| entry.distance <= cap);+ matches.truncate(keep);+ }+ results.push(KeyMatches {+ key: key.clone(),+ matches,+ truncated,+ });+ }+ Ok(results)}pub fn flush(&self) -> Result<(), VecDbError> {@@ -385,30 +449,19 @@ impl VecDb {if self.read_only {return Err(VecDbError::ReadOnly);}- let mut half = self.shared.writer_half();- self.shared.ensure_open()?;- let WriterState { lock, log, .. } = take_writer_state(&mut half)?;- let mut st = self.shared.state_write();- self.shared.closed.store(true, Ordering::Release);- drop(log);- let removed = remove_index_files(&self.shared.path);- if let Ok(empty) = VectorArena::new(self.shared.dims) {- st.arena = empty;- st.graph = Graph::new();- st.total_records = 0;- }- if let Some(key) = &self.shared.registry_key- && let Some(slot) = existing_path_slot(key)+ close_live_instance(&self.shared)+ }++ pub fn purge(path: &Path) -> Result<(), VecDbError> {+ if let Ok(key) = registry_key_for(path)+ && let Some(slot) = existing_path_slot(&key){- let mut guard = lock_slot(&slot);- if std::ptr::eq(guard.live.as_ptr(), Arc::as_ptr(&self.shared)) {- guard.live = Weak::new();+ let live = lock_slot(&slot).live.upgrade();+ if let Some(shared) = live {+ return close_live_instance(&shared);}}- drop(st);- drop(lock);- drop(half);- removed+ remove_index_files(path)}pub fn stats(&self) -> Result<Stats, VecDbError> {@@ -472,6 +525,69 @@ fn take_writer_state(half: &mut WriterHalf) -> Result<WriterState, VecDbError> {}}+fn degenerate_distance_cut(params: &SearchParams) -> Result<bool, VecDbError> {+ if params.limit.is_none() && params.max_distance.is_none() {+ return Err(VecDbError::UnboundedSearch);+ }+ Ok(params+ .max_distance+ .is_some_and(|max_distance| !max_distance.is_finite() || max_distance < 0.0))+}++fn resolve_allowed_slots(+ state: &SearchState,+ allowed_keys: Option<&[String]>,+) -> Option<HashSet<u32>> {+ allowed_keys.map(|keys| {+ keys.iter()+ .filter_map(|key| state.arena.slot_of_key(key))+ .collect()+ })+}++fn search_in_state(+ state: &SearchState,+ query: &[f32],+ params: &SearchParams,+ allowed_slots: Option<&HashSet<u32>>,+) -> Result<Vec<Match>, VecDbError> {+ let packed = state.arena.pack_query(query)?;+ Ok(graph_search(+ &state.graph,+ &state.arena,+ &packed,+ params,+ allowed_slots,+ ))+}++fn close_live_instance(shared: &Arc<Shared>) -> Result<(), VecDbError> {+ let mut half = shared.writer_half();+ shared.ensure_open()?;+ let WriterState { lock, log, .. } = take_writer_state(&mut half)?;+ let mut st = shared.state_write();+ shared.closed.store(true, Ordering::Release);+ drop(log);+ let removed = remove_index_files(&shared.path);+ if let Ok(empty) = VectorArena::new(shared.dims) {+ st.arena = empty;+ st.graph = Graph::new();+ st.total_records = 0;+ }+ if let Some(key) = &shared.registry_key+ && let Some(slot) = existing_path_slot(key)+ {+ let mut guard = lock_slot(&slot);+ if std::ptr::eq(guard.live.as_ptr(), Arc::as_ptr(shared)) {+ guard.live = Weak::new();+ }+ }+ drop(st);+ drop(lock);+ drop(half);+ removed+}+fn apply_add(shared: &Shared, key: &str, vector: &[f32]) -> Result<(), VecDbError> {let mut st = shared.state_write();let SearchState {@@ -999,6 +1115,11 @@ mod tests {.collect()}+ fn bulk_add(db: &VecDb, entries: &[(String, Vec<f32>)]) -> Result<(), VecDbError> {+ let (keys, vectors): (Vec<String>, Vec<Vec<f32>>) = entries.iter().cloned().unzip();+ db.bulk_add(&keys, &vectors)+ }+fn limit_params(limit: usize) -> SearchParams {SearchParams {limit: Some(limit),@@ -1109,7 +1230,7 @@ mod tests {let path = dir.path().join("db");let probe = seeded_unit_vector(777, DIMS);let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 150, 100)).unwrap();+ bulk_add(&db, &bulk_entries(0, 150, 100)).unwrap();db.add("probe", &probe).unwrap();assert_eq!(db.len(), 151);assert!(!db.is_empty());@@ -1169,7 +1290,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 10)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 10)).unwrap();let query = seeded_unit_vector(1, DIMS);assert!(matches!(db.search(&query, &SearchParams::default()),@@ -1224,7 +1345,7 @@ mod tests {).unwrap();}- db.bulk_add(&bulk_entries(0, 6, 40)).unwrap();+ bulk_add(&db, &bulk_entries(0, 6, 40)).unwrap();drop(db);let reopened = open_writer(&path);assert_eq!(reopened.len(), 10);@@ -1244,7 +1365,7 @@ mod tests {let path = dir.path().join("db");let copy = dir.path().join("copy");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 6, 60)).unwrap();+ bulk_add(&db, &bulk_entries(0, 6, 60)).unwrap();fs::copy(&path, ©).unwrap();let copied = open_writer(©);assert_eq!(copied.len(), 6);@@ -1264,7 +1385,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 4, 20)).unwrap();+ bulk_add(&db, &bulk_entries(0, 4, 20)).unwrap();drop(db);let clean_len = fs::metadata(&path).unwrap().len();let mut bytes = fs::read(&path).unwrap();@@ -1282,7 +1403,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 4, 30)).unwrap();+ bulk_add(&db, &bulk_entries(0, 4, 30)).unwrap();db.flush().unwrap();drop(db);let clean_len = fs::metadata(&path).unwrap().len();@@ -1301,7 +1422,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 8, 50)).unwrap();+ bulk_add(&db, &bulk_entries(0, 8, 50)).unwrap();db.flush().unwrap();drop(db);fs::remove_file(snapshot_path(&path)).unwrap();@@ -1316,7 +1437,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 70)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 70)).unwrap();db.flush().unwrap();drop(db);let stale_snapshot = fs::read(snapshot_path(&path)).unwrap();@@ -1338,7 +1459,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 80)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 80)).unwrap();db.flush().unwrap();drop(db);let bytes = fs::read(&path).unwrap();@@ -1355,7 +1476,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 90)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 90)).unwrap();db.flush().unwrap();drop(db);let mut bytes = fs::read(snapshot_path(&path)).unwrap();@@ -1371,7 +1492,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 110)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 110)).unwrap();db.flush().unwrap();drop(db);fs::write(temp_sibling(&path), [0xAB; 100]).unwrap();@@ -1391,7 +1512,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 120)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 120)).unwrap();let joined = VecDb::open(&path, DIMS).unwrap();assert!(Arc::ptr_eq(&db.shared, &joined.shared));assert_eq!(joined.len(), 3);@@ -1524,7 +1645,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 120, 340)).unwrap();+ bulk_add(&db, &bulk_entries(0, 120, 340)).unwrap();let generation_before = generation_of(&path);let removals: Vec<String> = (0..64).map(|index| format!("key-{index}")).collect();assert_eq!(db.bulk_remove(&removals).unwrap(), 64);@@ -1564,7 +1685,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 130)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 130)).unwrap();let read_only = VecDb::open_read_only(&path, DIMS).unwrap();assert!(Arc::ptr_eq(&db.shared, &read_only.shared));assert_eq!(read_only.len(), 3);@@ -1638,10 +1759,13 @@ mod tests {Err(VecDbError::ReadOnly)));assert!(matches!(- read_only.bulk_add(&bulk_entries(0, 2, 5)),+ bulk_add(&read_only, &bulk_entries(0, 2, 5)),+ Err(VecDbError::ReadOnly)+ ));+ assert!(matches!(+ bulk_add(&read_only, &[]),Err(VecDbError::ReadOnly)));- assert!(matches!(read_only.bulk_add(&[]), Err(VecDbError::ReadOnly)));assert!(matches!(read_only.remove("kept"),Err(VecDbError::ReadOnly)@@ -1662,7 +1786,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 100, 140)).unwrap();+ bulk_add(&db, &bulk_entries(0, 100, 140)).unwrap();drop(db);let snapshot_view = VecDb::open_read_only(&path, DIMS).unwrap();assert_eq!(snapshot_view.len(), 100);@@ -1779,7 +1903,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 150)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 150)).unwrap();let log_bytes = db.stats().unwrap().log_bytes;assert!(!db.remove("missing").unwrap());assert_eq!(db.stats().unwrap().log_bytes, log_bytes);@@ -1798,7 +1922,7 @@ mod tests {log_bytes + 2 * TOMBSTONE_RECORD_LEN);assert_eq!(db.bulk_remove(&[]).unwrap(), 0);- db.bulk_add(&[]).unwrap();+ bulk_add(&db, &[]).unwrap();assert_eq!(db.stats().unwrap().log_bytes,log_bytes + 2 * TOMBSTONE_RECORD_LEN@@ -1849,7 +1973,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 2, 160)).unwrap();+ bulk_add(&db, &bulk_entries(0, 2, 160)).unwrap();assert!(!snapshot_exists(&path));assert_eq!(db.stats().unwrap().records_since_snapshot, 2);db.flush().unwrap();@@ -1865,7 +1989,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 170)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 170)).unwrap();drop(db);assert!(!snapshot_exists(&path));drop(open_writer(&path));@@ -1883,7 +2007,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 120, 1000)).unwrap();+ bulk_add(&db, &bulk_entries(0, 120, 1000)).unwrap();let generation_before = generation_of(&path);for index in 0..40u64 {db.add(@@ -1942,7 +2066,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 1100, 3000)).unwrap();+ bulk_add(&db, &bulk_entries(0, 1100, 3000)).unwrap();let generation_before = generation_of(&path);let removals: Vec<String> = (0..58).map(|index| format!("key-{index}")).collect();assert_eq!(db.bulk_remove(&removals).unwrap(), 58);@@ -1969,7 +2093,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 120, 210)).unwrap();+ bulk_add(&db, &bulk_entries(0, 120, 210)).unwrap();db.flush().unwrap();let stale_snapshot = fs::read(snapshot_path(&path)).unwrap();let removals: Vec<String> = (0..64).map(|index| format!("key-{index}")).collect();@@ -2051,7 +2175,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 260)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 260)).unwrap();let WriterState { lock, log, .. } = take_writer(&db);drop(log);assert!(is_degraded(&db));@@ -2085,7 +2209,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 3, 270)).unwrap();+ bulk_add(&db, &bulk_entries(0, 3, 270)).unwrap();let WriterState { lock, log, .. } = take_writer(&db);drop(log);let mut bytes = fs::read(&path).unwrap();@@ -2130,7 +2254,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 100, 280)).unwrap();+ bulk_add(&db, &bulk_entries(0, 100, 280)).unwrap();let generation_before = generation_of(&path);fs::create_dir(temp_sibling(&path)).unwrap();let removals: Vec<String> = (0..64).map(|index| format!("key-{index}")).collect();@@ -2143,10 +2267,10 @@ mod tests {Err(VecDbError::Locked(_))));fs::remove_dir(temp_sibling(&path)).unwrap();- db.bulk_add(&bulk_entries(64, 36, 290)).unwrap();+ bulk_add(&db, &bulk_entries(64, 36, 290)).unwrap();assert_eq!(db.stats().unwrap().dead_count, 164);assert_eq!(generation_of(&path), generation_before);- db.bulk_add(&bulk_entries(64, 28, 295)).unwrap();+ bulk_add(&db, &bulk_entries(64, 28, 295)).unwrap();assert_eq!(db.stats().unwrap().dead_count, 0);assert_ne!(generation_of(&path), generation_before);drop(db);@@ -2162,7 +2286,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 300)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 300)).unwrap();drop(db);fs::create_dir(snapshot_path(&path)).unwrap();let db = open_writer(&path);@@ -2180,7 +2304,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 20, 180)).unwrap();+ bulk_add(&db, &bulk_entries(0, 20, 180)).unwrap();db.flush().unwrap();let generation_before = generation_of(&path);db.reset().unwrap();@@ -2214,7 +2338,7 @@ mod tests {let path = dir.path().join("db");let first = open_writer(&path);let second = VecDb::open(&path, DIMS).unwrap();- first.bulk_add(&bulk_entries(0, 10, 220)).unwrap();+ bulk_add(&first, &bulk_entries(0, 10, 220)).unwrap();assert_eq!(second.len(), 10);second.reset().unwrap();assert!(first.is_empty());@@ -2231,7 +2355,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 310)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 310)).unwrap();fs::create_dir(snapshot_path(&path)).unwrap();assert!(matches!(db.reset(), Err(VecDbError::Io { .. })));assert!(!path.exists());@@ -2256,7 +2380,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 320)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 320)).unwrap();fs::set_permissions(dir.path(), fs::Permissions::from_mode(0o555)).unwrap();let outcome = db.reset();fs::set_permissions(dir.path(), fs::Permissions::from_mode(0o755)).unwrap();@@ -2278,7 +2402,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 330)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 330)).unwrap();let old_generation = generation_of(&path);let WriterState { lock, log, .. } = take_writer(&db);drop(log);@@ -2305,7 +2429,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 5, 190)).unwrap();+ bulk_add(&db, &bulk_entries(0, 5, 190)).unwrap();db.flush().unwrap();fs::write(temp_sibling(&path), [7u8; 10]).unwrap();assert!(path.exists());@@ -2323,7 +2447,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let first = open_writer(&path);- first.bulk_add(&bulk_entries(0, 5, 400)).unwrap();+ bulk_add(&first, &bulk_entries(0, 5, 400)).unwrap();first.flush().unwrap();let survivor = VecDb::open(&path, DIMS).unwrap();let observer = VecDb::open_read_only(&path, DIMS).unwrap();@@ -2338,7 +2462,7 @@ mod tests {));assert!(matches!(survivor.add("x", &query), Err(VecDbError::Closed)));assert!(matches!(- survivor.bulk_add(&bulk_entries(0, 2, 401)),+ bulk_add(&survivor, &bulk_entries(0, 2, 401)),Err(VecDbError::Closed)));assert!(matches!(survivor.remove("key-0"), Err(VecDbError::Closed)));@@ -2367,7 +2491,7 @@ mod tests {let path = dir.path().join("db");let writer = open_writer(&path);let pre = bulk_entries(10_000, 50, 900);- writer.bulk_add(&pre).unwrap();+ bulk_add(&writer, &pre).unwrap();let bulk = bulk_entries(0, BULK, 700);let expected: Arc<HashMap<String, Vec<f32>>> =Arc::new(pre.iter().chain(bulk.iter()).cloned().collect());@@ -2415,7 +2539,7 @@ mod tests {})};barrier.wait();- writer.bulk_add(&bulk).unwrap();+ bulk_add(&writer, &bulk).unwrap();stop.store(true, Ordering::Relaxed);for reader in readers {let (handle, iterations) = reader.join().unwrap();@@ -2435,7 +2559,7 @@ mod tests {let dir = TempDir::new().unwrap();let path = dir.path().join("db");let db = open_writer(&path);- db.bulk_add(&bulk_entries(0, 300, 500)).unwrap();+ bulk_add(&db, &bulk_entries(0, 300, 500)).unwrap();let removals: Vec<String> = (0..30).map(|index| format!("key-{index}")).collect();assert_eq!(db.bulk_remove(&removals).unwrap(), 30);assert_eq!(db.stats().unwrap().dead_count, 60);@@ -2489,7 +2613,7 @@ mod tests {let mut infected = bulk_entries(10, 3, 200);infected[1].1[0] = f32::INFINITY;assert!(matches!(- db.bulk_add(&infected),+ bulk_add(&db, &infected),Err(VecDbError::InvalidVector(_))));assert_eq!(db.len(), 1);@@ -2502,4 +2626,304 @@ mod tests {assert!(reopened.contains("key-0"));assert!(!reopened.contains("bad"));}++ #[test]+ fn bulk_search_matches_per_query_search() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ bulk_add(&db, &bulk_entries(0, 200, 640)).unwrap();+ let allowed = vec![+ "key-3".to_string(),+ "key-77".to_string(),+ "key-77".to_string(),+ "key-150".to_string(),+ "absent".to_string(),+ ];+ let queries: Vec<Vec<f32>> = (0..6)+ .map(|index| seeded_unit_vector(9000 + index, DIMS))+ .collect();+ for shape in search_shapes(allowed) {+ let bulk = db.bulk_search(&queries, &shape).unwrap();+ assert_eq!(bulk.len(), queries.len());+ for (query, matches) in queries.iter().zip(&bulk) {+ assert_eq!(matches, &db.search(query, &shape).unwrap());+ }+ }+ assert!(matches!(+ db.bulk_search(&queries, &SearchParams::default()),+ Err(VecDbError::UnboundedSearch)+ ));+ for bad_distance in [f32::NAN, f32::INFINITY, -0.5] {+ let degenerate = SearchParams {+ limit: Some(3),+ max_distance: Some(bad_distance),+ ..SearchParams::default()+ };+ let empties = db.bulk_search(&queries, °enerate).unwrap();+ assert_eq!(empties.len(), queries.len());+ assert!(empties.iter().all(Vec::is_empty));+ }+ let empty_allowed = SearchParams {+ limit: Some(5),+ allowed_keys: Some(Vec::new()),+ ..SearchParams::default()+ };+ let none_allowed = db.bulk_search(&queries, &empty_allowed).unwrap();+ assert_eq!(none_allowed.len(), queries.len());+ assert!(none_allowed.iter().all(Vec::is_empty));+ for query in &queries {+ assert!(db.search(query, &empty_allowed).unwrap().is_empty());+ }+ assert!(db.bulk_search(&[], &limit_params(3)).unwrap().is_empty());+ }++ #[test]+ fn bulk_search_stored_preserves_order_skips_absent_and_excludes_self() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ bulk_add(&db, &bulk_entries(0, 40, 820)).unwrap();+ let twin = seeded_unit_vector(31_000, DIMS);+ db.add("twin-a", &twin).unwrap();+ db.add("twin-b", &twin).unwrap();+ let input = vec![+ "key-5".to_string(),+ "missing".to_string(),+ "twin-a".to_string(),+ "key-0".to_string(),+ "key-31".to_string(),+ ];+ for exact in [false, true] {+ let results = db+ .bulk_search_stored(&input, 4, None, exact, false)+ .unwrap();+ let found: Vec<&str> = results.iter().map(|entry| entry.key.as_str()).collect();+ assert_eq!(found, vec!["key-5", "twin-a", "key-0", "key-31"]);+ for entry in &results {+ assert_eq!(entry.matches.len(), 4);+ assert!(entry.truncated);+ assert!(entry.matches.iter().all(|found| found.key != entry.key));+ }+ assert_eq!(results[1].matches[0].key, "twin-b");+ assert!(results[1].matches[0].distance.abs() < 1.0e-6);+ }+ assert!(+ db.bulk_search_stored(&[], 3, None, false, false)+ .unwrap()+ .is_empty()+ );+ let absent = vec!["nope".to_string(), "nada".to_string()];+ assert!(+ db.bulk_search_stored(&absent, 3, None, true, true)+ .unwrap()+ .is_empty()+ );+ }++ #[test]+ fn bulk_search_stored_restricts_to_input_only_when_asked() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ bulk_add(&db, &bulk_entries(0, 30, 860)).unwrap();+ let input: Vec<String> = (1..=4).map(|index| format!("key-{index}")).collect();+ for exact in [false, true] {+ let restricted = db+ .bulk_search_stored(&input, 10, None, exact, true)+ .unwrap();+ assert_eq!(restricted.len(), 4);+ for entry in &restricted {+ assert_eq!(entry.matches.len(), 3);+ assert!(!entry.truncated);+ assert!(+ entry+ .matches+ .iter()+ .all(|found| input.contains(&found.key) && found.key != entry.key)+ );+ }+ let open = db+ .bulk_search_stored(&input, 10, None, exact, false)+ .unwrap();+ assert!(open.iter().all(|entry| entry.matches.len() == 10));+ assert!(open.iter().any(|entry| {+ entry+ .matches+ .iter()+ .any(|found| !input.contains(&found.key))+ }));+ }+ }++ #[test]+ fn bulk_search_stored_distance_cut_and_truncated_flag() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ db.add("center", &basis_vector(0)).unwrap();+ let mut close = basis_vector(0);+ close[0] = 0.99;+ close[1] = (1.0f32 - 0.99 * 0.99).sqrt();+ db.add("close", &close).unwrap();+ for axis in 2..10 {+ db.add(&format!("far-{axis}"), &basis_vector(axis)).unwrap();+ }+ let center = vec!["center".to_string()];+ for exact in [false, true] {+ let cut = db+ .bulk_search_stored(¢er, 5, Some(0.5), exact, false)+ .unwrap();+ assert_eq!(cut[0].matches.len(), 1);+ assert_eq!(cut[0].matches[0].key, "close");+ assert!(cut[0].truncated);+ let uncut = db+ .bulk_search_stored(¢er, 20, Some(0.5), exact, false)+ .unwrap();+ assert_eq!(uncut[0].matches.len(), 1);+ assert!(!uncut[0].truncated);+ let complete = db+ .bulk_search_stored(¢er, 9, None, exact, false)+ .unwrap();+ assert_eq!(complete[0].matches.len(), 9);+ assert!(complete[0].truncated);+ let whole_index = db+ .bulk_search_stored(¢er, 10, None, exact, false)+ .unwrap();+ assert_eq!(whole_index[0].matches.len(), 9);+ assert!(!whole_index[0].truncated);+ for bad_distance in [f32::NAN, f32::INFINITY, -0.5] {+ let degenerate = db+ .bulk_search_stored(¢er, 5, Some(bad_distance), exact, false)+ .unwrap();+ assert_eq!(degenerate.len(), 1);+ assert!(degenerate[0].matches.is_empty());+ assert!(!degenerate[0].truncated);+ }+ }+ }++ #[test]+ fn bulk_search_stored_on_a_single_entry_index_finds_nothing() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ db.add("solo", &seeded_unit_vector(5, DIMS)).unwrap();+ let input = vec!["solo".to_string()];+ for exact in [false, true] {+ for restrict in [false, true] {+ let results = db+ .bulk_search_stored(&input, 3, None, exact, restrict)+ .unwrap();+ assert_eq!(results.len(), 1);+ assert_eq!(results[0].key, "solo");+ assert!(results[0].matches.is_empty());+ assert!(!results[0].truncated);+ }+ }+ }++ #[test]+ fn bulk_add_length_mismatch_is_rejected_before_anything_else() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ db.add("seed", &seeded_unit_vector(1, DIMS)).unwrap();+ let log_bytes = db.stats().unwrap().log_bytes;+ let keys = vec!["x".to_string(), "y".to_string()];+ let vectors = vec![seeded_unit_vector(2, DIMS)];+ assert!(matches!(+ db.bulk_add(&keys, &vectors),+ Err(VecDbError::LengthMismatch {+ keys: 2,+ vectors: 1+ })+ ));+ assert_eq!(db.len(), 1);+ assert!(!db.contains("x"));+ assert_eq!(db.stats().unwrap().log_bytes, log_bytes);+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();+ assert!(matches!(+ read_only.bulk_add(&keys, &vectors),+ Err(VecDbError::LengthMismatch { .. })+ ));+ }++ #[test]+ fn purge_with_a_live_instance_behaves_like_delete() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let first = open_writer(&path);+ bulk_add(&first, &bulk_entries(0, 5, 950)).unwrap();+ first.flush().unwrap();+ fs::write(temp_sibling(&path), [7u8; 10]).unwrap();+ let survivor = VecDb::open(&path, DIMS).unwrap();+ let observer = VecDb::open_read_only(&path, DIMS).unwrap();+ VecDb::purge(&path).unwrap();+ assert!(!path.exists());+ assert!(!snapshot_exists(&path));+ assert!(!temp_sibling(&path).exists());+ assert!(!lock_path(&path).exists());+ let query = seeded_unit_vector(1, DIMS);+ assert!(matches!(+ survivor.search(&query, &limit_params(3)),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(+ survivor.bulk_search(std::slice::from_ref(&query), &limit_params(3)),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(+ survivor.bulk_search_stored(&["key-0".to_string()], 3, None, false, false),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(survivor.add("x", &query), Err(VecDbError::Closed)));+ assert!(matches!(+ bulk_add(&survivor, &bulk_entries(0, 2, 951)),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(survivor.remove("key-0"), Err(VecDbError::Closed)));+ assert!(matches!(+ survivor.bulk_remove(&["key-0".to_string()]),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(survivor.stats(), Err(VecDbError::Closed)));+ assert!(matches!(survivor.flush(), Err(VecDbError::Closed)));+ assert!(matches!(survivor.reset(), Err(VecDbError::Closed)));+ assert!(matches!(+ observer.search(&query, &limit_params(3)),+ Err(VecDbError::Closed)+ ));+ assert!(matches!(first.stats(), Err(VecDbError::Closed)));+ assert!(matches!(survivor.delete(), Err(VecDbError::Closed)));+ let fresh = open_writer(&path);+ assert!(fresh.is_empty());+ fresh.add("anew", &query).unwrap();+ assert_eq!(fresh.len(), 1);+ }++ #[test]+ fn purge_without_a_live_instance_removes_files_and_tolerates_missing_ones() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let db = open_writer(&path);+ bulk_add(&db, &bulk_entries(0, 5, 960)).unwrap();+ db.flush().unwrap();+ drop(db);+ fs::write(temp_sibling(&path), [7u8; 10]).unwrap();+ assert!(path.exists());+ assert!(snapshot_exists(&path));+ assert!(lock_path(&path).exists());+ VecDb::purge(&path).unwrap();+ assert!(!path.exists());+ assert!(!snapshot_exists(&path));+ assert!(!temp_sibling(&path).exists());+ assert!(!lock_path(&path).exists());+ VecDb::purge(&path).unwrap();+ VecDb::purge(&dir.path().join("never-created")).unwrap();+ let fresh = open_writer(&path);+ assert!(fresh.is_empty());+ fresh.add("fresh", &seeded_unit_vector(3, DIMS)).unwrap();+ assert_eq!(fresh.len(), 1);+ }}