Skip to content

armgit / ente

Public Imported from GitHub
0

πŸ’š End-to-end encrypted cloud for everything.

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.rs
index 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, &params)
- }
-
- 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, &params)?))
}
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, &params))
- .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, &params)?;
+ 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, &params))
- .collect()
+ let results = self.inner.bulk_search(&queries, &params)?;
+ 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, &params)?;
- 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.rs
index 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) -> IngestTimings
let 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.rs
index 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,
+ &params(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,
+ &params(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,
+ &params(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,
+ &params(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,
+ &params(Some(5), None, exact),
+ filter,
+ Some(0),
+ );
+ assert!(by_limit.is_empty());
+ let by_threshold = search_excluding(
+ &graph,
+ &arena,
+ &query,
+ &params(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.rs
index 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.rs
index 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),
+ &params,
+ 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, &copy).unwrap();
let copied = open_writer(&copy);
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, &degenerate).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(&center, 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(&center, 20, Some(0.5), exact, false)
+ .unwrap();
+ assert_eq!(uncut[0].matches.len(), 1);
+ assert!(!uncut[0].truncated);
+ let complete = db
+ .bulk_search_stored(&center, 9, None, exact, false)
+ .unwrap();
+ assert_eq!(complete[0].matches.len(), 9);
+ assert!(complete[0].truncated);
+ let whole_index = db
+ .bulk_search_stored(&center, 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(&center, 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);
+ }
}