Skip to content

armgit / ente

Public Imported from GitHub
0

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

vecdb: optional typed per-entry attributes

laurenspriem8adfa35056bc
diff --git a/rust/bindings/frb/photos/src/api/vecdb_api.rs b/rust/bindings/frb/photos/src/api/vecdb_api.rs
index 628c00e482..557880120a 100644
--- a/rust/bindings/frb/photos/src/api/vecdb_api.rs
+++ b/rust/bindings/frb/photos/src/api/vecdb_api.rs
@@ -12,6 +12,7 @@ pub enum RustVecDbError {
Closed { message: String },
InvalidKey { message: String },
InvalidVector { message: String },
+ InvalidAttributes { message: String },
DimensionMismatch { message: String },
InvalidDimensions { message: String },
UnboundedSearch { message: String },
@@ -29,6 +30,7 @@ impl From<vecdb::VecDbError> for RustVecDbError {
vecdb::VecDbError::Closed => Self::Closed { message },
vecdb::VecDbError::InvalidKey(_) => Self::InvalidKey { message },
vecdb::VecDbError::InvalidVector(_) => Self::InvalidVector { message },
+ vecdb::VecDbError::InvalidAttributes(_) => Self::InvalidAttributes { message },
vecdb::VecDbError::DimensionMismatch { .. } => Self::DimensionMismatch { message },
vecdb::VecDbError::InvalidDimensions(_) => Self::InvalidDimensions { message },
vecdb::VecDbError::UnboundedSearch => Self::UnboundedSearch { message },
@@ -37,6 +39,51 @@ impl From<vecdb::VecDbError> for RustVecDbError {
}
}
+#[derive(Clone, Debug)]
+pub enum VecDbAttrValue {
+ Str(String),
+ Bool(bool),
+ I64(i64),
+ F64(f64),
+}
+
+#[derive(Clone, Debug)]
+pub struct VecDbAttr {
+ pub name: String,
+ pub value: VecDbAttrValue,
+}
+
+fn to_engine_attr(attr: VecDbAttr) -> vecdb::Attribute {
+ vecdb::Attribute {
+ name: attr.name,
+ value: match attr.value {
+ VecDbAttrValue::Str(value) => vecdb::AttrValue::Str(value),
+ VecDbAttrValue::Bool(value) => vecdb::AttrValue::Bool(value),
+ VecDbAttrValue::I64(value) => vecdb::AttrValue::I64(value),
+ VecDbAttrValue::F64(value) => vecdb::AttrValue::F64(value),
+ },
+ }
+}
+
+fn to_engine_attrs(attrs: Vec<VecDbAttr>) -> Vec<vecdb::Attribute> {
+ attrs.into_iter().map(to_engine_attr).collect()
+}
+
+fn to_api_attrs(attrs: Vec<vecdb::Attribute>) -> Vec<VecDbAttr> {
+ attrs
+ .into_iter()
+ .map(|attr| VecDbAttr {
+ name: attr.name,
+ value: match attr.value {
+ vecdb::AttrValue::Str(value) => VecDbAttrValue::Str(value),
+ vecdb::AttrValue::Bool(value) => VecDbAttrValue::Bool(value),
+ vecdb::AttrValue::I64(value) => VecDbAttrValue::I64(value),
+ vecdb::AttrValue::F64(value) => VecDbAttrValue::F64(value),
+ },
+ })
+ .collect()
+}
+
#[derive(Clone, Debug)]
pub struct VecDbMatch {
pub key: String,
@@ -130,6 +177,42 @@ impl VecDb {
Ok(self.inner.bulk_add(&keys, &vectors)?)
}
+ pub fn add_vector_with_attrs(
+ &self,
+ key: String,
+ vector: Vec<f32>,
+ attrs: Vec<VecDbAttr>,
+ ) -> Result<(), RustVecDbError> {
+ Ok(self
+ .inner
+ .add_with_attrs(&key, &vector, &to_engine_attrs(attrs))?)
+ }
+
+ pub fn bulk_add_vectors_with_attrs(
+ &self,
+ keys: Vec<String>,
+ vectors: Vec<Vec<f32>>,
+ attrs: Vec<Option<Vec<VecDbAttr>>>,
+ ) -> Result<(), RustVecDbError> {
+ let attrs: Vec<Option<Vec<vecdb::Attribute>>> = attrs
+ .into_iter()
+ .map(|entry| entry.map(to_engine_attrs))
+ .collect();
+ Ok(self.inner.bulk_add_with_attrs(&keys, &vectors, &attrs)?)
+ }
+
+ pub fn get_attrs(&self, key: String) -> Option<Vec<VecDbAttr>> {
+ self.inner.get_attrs(&key).map(to_api_attrs)
+ }
+
+ pub fn bulk_get_attrs(&self, keys: Vec<String>) -> Vec<Option<Vec<VecDbAttr>>> {
+ self.inner
+ .bulk_get_attrs(&keys)
+ .into_iter()
+ .map(|entry| entry.map(to_api_attrs))
+ .collect()
+ }
+
pub fn approx_search_vectors_within_similarity(
&self,
query: Vec<f32>,
@@ -552,6 +635,95 @@ mod tests {
assert!(cut[0].matches.is_empty());
}
+ #[test]
+ fn attrs_round_trip_through_the_api() {
+ let dir = TestDir::create();
+ let db = VecDb::new(dir.db_path(), DIMS).unwrap();
+ let attrs = vec![
+ VecDbAttr {
+ name: key("model"),
+ value: VecDbAttrValue::Str("clip".to_string()),
+ },
+ VecDbAttr {
+ name: key("version"),
+ value: VecDbAttrValue::I64(3),
+ },
+ VecDbAttr {
+ name: key("indexed"),
+ value: VecDbAttrValue::Bool(true),
+ },
+ VecDbAttr {
+ name: key("score"),
+ value: VecDbAttrValue::F64(0.75),
+ },
+ ];
+ db.add_vector_with_attrs(key("a"), basis(0), attrs.clone())
+ .unwrap();
+ let fetched = db.get_attrs(key("a")).unwrap();
+ assert_eq!(fetched.len(), 4);
+ assert!(matches!(
+ &fetched[0],
+ VecDbAttr { name, value: VecDbAttrValue::Str(value) }
+ if name == "model" && value == "clip"
+ ));
+ assert!(matches!(
+ &fetched[1],
+ VecDbAttr { name, value: VecDbAttrValue::I64(3) } if name == "version"
+ ));
+ assert!(matches!(
+ &fetched[2],
+ VecDbAttr { name, value: VecDbAttrValue::Bool(true) } if name == "indexed"
+ ));
+ assert!(matches!(
+ &fetched[3],
+ VecDbAttr { name, value: VecDbAttrValue::F64(value) } if name == "score" && *value == 0.75
+ ));
+ db.bulk_add_vectors_with_attrs(
+ vec![key("b"), key("c")],
+ vec![basis(1), basis(2)],
+ vec![
+ Some(vec![VecDbAttr {
+ name: key("only"),
+ value: VecDbAttrValue::Bool(false),
+ }]),
+ None,
+ ],
+ )
+ .unwrap();
+ let bulk = db.bulk_get_attrs(vec![key("b"), key("c"), key("missing")]);
+ assert_eq!(bulk.len(), 3);
+ assert!(matches!(
+ bulk[0].as_deref(),
+ Some([VecDbAttr { name, value: VecDbAttrValue::Bool(false) }]) if name == "only"
+ ));
+ assert!(bulk[1].is_none());
+ assert!(bulk[2].is_none());
+ db.add_vector(key("a"), basis(0)).unwrap();
+ assert!(db.get_attrs(key("a")).is_none());
+ assert!(matches!(
+ db.add_vector_with_attrs(
+ key("a"),
+ basis(0),
+ vec![
+ VecDbAttr {
+ name: key("dup"),
+ value: VecDbAttrValue::Bool(true),
+ },
+ VecDbAttr {
+ name: key("dup"),
+ value: VecDbAttrValue::Bool(false),
+ },
+ ],
+ ),
+ Err(RustVecDbError::InvalidAttributes { .. })
+ ));
+ assert!(matches!(
+ db.bulk_add_vectors_with_attrs(vec![key("x")], vec![basis(3)], vec![None, None]),
+ Err(RustVecDbError::LengthMismatch { .. })
+ ));
+ assert_eq!(db.get_index_stats().unwrap().live_count, 3);
+ }
+
#[test]
fn delete_vec_db_files_purges_with_and_without_live_instances() {
let dir = TestDir::create();
diff --git a/rust/crates/ml/examples/vecdb_bench.rs b/rust/crates/ml/examples/vecdb_bench.rs
index 6f654bf200..93cc90fcaa 100644
--- a/rust/crates/ml/examples/vecdb_bench.rs
+++ b/rust/crates/ml/examples/vecdb_bench.rs
@@ -2,7 +2,7 @@ use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
-use ente_ml::vecdb::{Match, SearchParams, VecDb};
+use ente_ml::vecdb::{AttrValue, Attribute, Match, SearchParams, VecDb};
const SEED: u64 = 0xE47E_0000_0000_0001;
const LATENT_DIMS: usize = 24;
@@ -19,6 +19,7 @@ const DEFAULT_DIMS: usize = 512;
struct Config {
scales: Vec<usize>,
dims: usize,
+ attrs: bool,
}
struct BenchData {
@@ -57,8 +58,11 @@ struct VecdbReport {
fn main() {
let config = parse_args();
println!(
- "vecdb bench dims={} queries={} seed={:#018x}",
- config.dims, QUERY_COUNT, SEED
+ "vecdb bench dims={} queries={} seed={:#018x}{}",
+ config.dims,
+ QUERY_COUNT,
+ SEED,
+ if config.attrs { " attrs=on" } else { "" }
);
println!(
"scales: {}",
@@ -71,13 +75,14 @@ fn main() {
);
let temp_root = tempfile::TempDir::new().expect("create bench temp dir");
for &scale in &config.scales {
- run_scale(scale, config.dims, temp_root.path());
+ run_scale(scale, config.dims, config.attrs, temp_root.path());
}
}
fn parse_args() -> Config {
let mut scales = parse_scales(DEFAULT_SCALES);
let mut dims = DEFAULT_DIMS;
+ let mut attrs = false;
let mut args = std::env::args().skip(1);
while let Some(arg) = args.next() {
match arg.as_str() {
@@ -87,6 +92,7 @@ fn parse_args() -> Config {
.parse()
.unwrap_or_else(|_| usage_exit())
}
+ "--attrs" => attrs = true,
_ => usage_exit(),
}
}
@@ -94,7 +100,11 @@ fn parse_args() -> Config {
eprintln!("--dims must be a nonzero multiple of 8");
std::process::exit(2);
}
- Config { scales, dims }
+ Config {
+ scales,
+ dims,
+ attrs,
+ }
}
fn required_value(value: Option<String>) -> String {
@@ -118,12 +128,12 @@ fn parse_scales(list: &str) -> Vec<usize> {
fn usage_exit() -> ! {
eprintln!(
"usage: cargo run -p ente-ml --example vecdb_bench --release -- \
- [--scales 10000,100000] [--dims 512]"
+ [--scales 10000,100000] [--dims 512] [--attrs]"
);
std::process::exit(2);
}
-fn run_scale(scale: usize, dims: usize, temp_root: &Path) {
+fn run_scale(scale: usize, dims: usize, attrs: bool, temp_root: &Path) {
let clusters = (scale / 150).max(1) as u64;
println!();
println!("=== scale {scale} dims {dims} clusters {clusters} ===");
@@ -131,7 +141,7 @@ fn run_scale(scale: usize, dims: usize, temp_root: &Path) {
let data = generate_data(scale, dims, clusters);
let dir = temp_root.join(format!("scale-{scale}-{dims}"));
std::fs::create_dir_all(&dir).expect("create bench dir");
- let vecdb = run_vecdb(&data, dims, &dir, scale);
+ let vecdb = run_vecdb(&data, dims, attrs, &dir, scale);
print_vecdb_report(&vecdb);
let _ = std::fs::remove_dir_all(&dir);
}
@@ -255,10 +265,10 @@ struct CompactionTimings {
compaction_fired: bool,
}
-fn run_vecdb(data: &BenchData, dims: usize, dir: &Path, scale: usize) -> VecdbReport {
+fn run_vecdb(data: &BenchData, dims: usize, attrs: bool, dir: &Path, scale: usize) -> VecdbReport {
let path = dir.join("bench.vecdb");
let mut db = VecDb::open(&path, dims).expect("open vecdb");
- let ingest = ingest_phase(&mut db, data, scale);
+ let ingest = ingest_phase(&mut db, data, attrs, scale);
let searches = search_phase(&db, data, scale);
let stats = db.stats().expect("vecdb stats");
let snapshot_file = PathBuf::from(format!("{}.graph", path.display()));
@@ -296,12 +306,41 @@ fn run_vecdb(data: &BenchData, dims: usize, dir: &Path, scale: usize) -> VecdbRe
}
}
-fn ingest_phase(db: &mut VecDb, data: &BenchData, scale: usize) -> IngestTimings {
+fn bench_attrs(index: usize) -> Vec<Attribute> {
+ vec![
+ Attribute {
+ name: "model".to_string(),
+ value: AttrValue::Str("mobileclip-s2-v2".to_string()),
+ },
+ Attribute {
+ name: "version".to_string(),
+ value: AttrValue::I64(index as i64),
+ },
+ Attribute {
+ name: "indexed".to_string(),
+ value: AttrValue::Bool(index.is_multiple_of(2)),
+ },
+ ]
+}
+
+fn ingest_phase(db: &mut VecDb, data: &BenchData, attrs: bool, scale: usize) -> IngestTimings {
let single_count = SINGLE_ADD_COUNT.min(data.entries.len());
eprintln!("[scale {scale}] vecdb single adds");
+ let single_attrs: Option<Vec<Vec<Attribute>>> =
+ attrs.then(|| (0..single_count).map(bench_attrs).collect());
let started = Instant::now();
- for (key, vector) in &data.entries[..single_count] {
- db.add(key, vector).expect("vecdb add");
+ match &single_attrs {
+ Some(all) => {
+ for ((key, vector), entry_attrs) in data.entries[..single_count].iter().zip(all) {
+ db.add_with_attrs(key, vector, entry_attrs)
+ .expect("vecdb add");
+ }
+ }
+ None => {
+ for (key, vector) in &data.entries[..single_count] {
+ db.add(key, vector).expect("vecdb add");
+ }
+ }
}
let single_total = started.elapsed();
let rest = &data.entries[single_count..];
@@ -310,9 +349,34 @@ fn ingest_phase(db: &mut VecDb, data: &BenchData, scale: usize) -> IngestTimings
.chunks(BULK_BATCH_SIZE)
.map(|batch| batch.iter().cloned().unzip())
.collect();
+ let bulk_attrs: Option<Vec<Vec<Option<Vec<Attribute>>>>> = attrs.then(|| {
+ batches
+ .iter()
+ .scan(single_count, |next_index, (keys, _)| {
+ let start = *next_index;
+ *next_index += keys.len();
+ Some(
+ (start..start + keys.len())
+ .map(bench_attrs)
+ .map(Some)
+ .collect(),
+ )
+ })
+ .collect()
+ });
let started = Instant::now();
- for (keys, vectors) in &batches {
- db.bulk_add(keys, vectors).expect("vecdb bulk add");
+ match &bulk_attrs {
+ Some(all) => {
+ for ((keys, vectors), batch_attrs) in batches.iter().zip(all) {
+ db.bulk_add_with_attrs(keys, vectors, batch_attrs)
+ .expect("vecdb bulk add");
+ }
+ }
+ None => {
+ 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/log.rs b/rust/crates/ml/src/vecdb/log.rs
index 8930b01022..e50d991519 100644
--- a/rust/crates/ml/src/vecdb/log.rs
+++ b/rust/crates/ml/src/vecdb/log.rs
@@ -4,10 +4,10 @@ use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};
-use super::VecDbError;
use super::arena::{MAX_KEY_BYTES, validate_key};
use super::crc::{Crc32, crc32};
use super::kernel::{LANE_WIDTH, splitmix64};
+use super::{AttrValue, Attribute, VecDbError};
pub(crate) const HEADER_LEN: usize = 32;
const MAGIC: [u8; 4] = *b"EVDB";
@@ -19,19 +19,39 @@ const RECORD_TYPE_TOMBSTONE: u8 = 2;
const RECORD_PREFIX_LEN: usize = 3;
const RECORD_CRC_LEN: usize = 4;
const ENCODE_FLUSH_BYTES: usize = 64 * 1024;
+const MAX_ATTR_COUNT: usize = 16;
+const MAX_ATTR_NAME_BYTES: usize = 64;
+const MAX_ATTR_STR_BYTES: usize = 1024;
+const MAX_ATTRS_TOTAL_BYTES: usize = 4096;
+const ATTR_TAG_STR: u8 = 0;
+const ATTR_TAG_BOOL: u8 = 1;
+const ATTR_TAG_I64: u8 = 2;
+const ATTR_TAG_F64: u8 = 3;
static GENERATION_COUNTER: AtomicU64 = AtomicU64::new(0);
#[derive(Debug, Clone, Copy)]
pub(crate) enum LogEntry<'a> {
- Add { key: &'a str, vector: &'a [f32] },
- Tombstone { key: &'a str },
+ Add {
+ key: &'a str,
+ vector: &'a [f32],
+ attrs: &'a [Attribute],
+ },
+ Tombstone {
+ key: &'a str,
+ },
}
#[derive(Debug, Clone, PartialEq)]
pub(crate) enum LogRecord {
- Add { key: String, vector: Vec<f32> },
- Tombstone { key: String },
+ Add {
+ key: String,
+ vector: Vec<f32>,
+ attrs: Vec<Attribute>,
+ },
+ Tombstone {
+ key: String,
+ },
}
#[derive(Debug)]
@@ -246,7 +266,7 @@ impl LogScanner<'_> {
self.done = true;
return Ok(None);
}
- if remaining < RECORD_PREFIX_LEN as u64 {
+ if remaining < (RECORD_PREFIX_LEN + RECORD_CRC_LEN) as u64 {
return Ok(self.stop());
}
let mut prefix = [0u8; RECORD_PREFIX_LEN];
@@ -255,58 +275,36 @@ impl LogScanner<'_> {
}
let record_type = prefix[0];
let key_len = u16::from_le_bytes([prefix[1], prefix[2]]) as usize;
- let payload_len = match record_type {
- RECORD_TYPE_ADD => self.dims * size_of::<f32>(),
- RECORD_TYPE_TOMBSTONE => 0,
+ if key_len == 0 || key_len > MAX_KEY_BYTES {
+ return Ok(self.stop());
+ }
+ let fixed_len = match record_type {
+ RECORD_TYPE_ADD => key_len + self.dims * size_of::<f32>() + 1,
+ RECORD_TYPE_TOMBSTONE => key_len,
_ => return Ok(self.stop()),
};
- if key_len == 0 || key_len > MAX_KEY_BYTES {
+ let body_budget = remaining - (RECORD_PREFIX_LEN + RECORD_CRC_LEN) as u64;
+ self.scratch.clear();
+ if fixed_len as u64 > body_budget || !self.fill_scratch(fixed_len)? {
return Ok(self.stop());
}
- let rest_len = key_len + payload_len + RECORD_CRC_LEN;
- if remaining < (RECORD_PREFIX_LEN + rest_len) as u64 {
+ if record_type == RECORD_TYPE_ADD && !self.read_attr_bytes(body_budget)? {
return Ok(self.stop());
}
- let mut scratch = std::mem::take(&mut self.scratch);
- scratch.resize(rest_len, 0);
- let filled = self.fill(&mut scratch)?;
- self.scratch = scratch;
- if !filled {
+ let mut crc_bytes = [0u8; RECORD_CRC_LEN];
+ if !self.fill(&mut crc_bytes)? {
return Ok(self.stop());
}
- let (body, stored_crc_bytes) = self.scratch.split_at(key_len + payload_len);
- let stored_crc = u32::from_le_bytes([
- stored_crc_bytes[0],
- stored_crc_bytes[1],
- stored_crc_bytes[2],
- stored_crc_bytes[3],
- ]);
let mut hasher = Crc32::new();
hasher.update(&prefix);
- hasher.update(body);
- if hasher.finalize() != stored_crc {
+ hasher.update(&self.scratch);
+ if hasher.finalize() != u32::from_le_bytes(crc_bytes) {
return Ok(self.stop());
}
- let (key_bytes, payload) = body.split_at(key_len);
- let Ok(key) = std::str::from_utf8(key_bytes) else {
+ let Some(record) = decode_body(record_type, key_len, self.dims, &self.scratch) else {
return Ok(self.stop());
};
- let record = if record_type == RECORD_TYPE_ADD {
- LogRecord::Add {
- key: key.to_string(),
- vector: payload
- .as_chunks::<4>()
- .0
- .iter()
- .map(|bytes| f32::from_le_bytes(*bytes))
- .collect(),
- }
- } else {
- LogRecord::Tombstone {
- key: key.to_string(),
- }
- };
- self.offset = start + (RECORD_PREFIX_LEN + rest_len) as u64;
+ self.offset = start + (RECORD_PREFIX_LEN + self.scratch.len() + RECORD_CRC_LEN) as u64;
Ok(Some((record, start)))
}
@@ -319,6 +317,74 @@ impl LogScanner<'_> {
None
}
+ fn read_attr_bytes(&mut self, body_budget: u64) -> Result<bool, VecDbError> {
+ let attr_count = *self.scratch.last().unwrap();
+ if attr_count as usize > MAX_ATTR_COUNT {
+ return Ok(false);
+ }
+ let attrs_start = self.scratch.len();
+ for _ in 0..attr_count {
+ if !self.extend_within(body_budget, 1)? {
+ return Ok(false);
+ }
+ let name_len = *self.scratch.last().unwrap() as usize;
+ if name_len == 0 || name_len > MAX_ATTR_NAME_BYTES {
+ return Ok(false);
+ }
+ if !self.extend_within(body_budget, name_len + 1)? {
+ return Ok(false);
+ }
+ let value_len = match *self.scratch.last().unwrap() {
+ ATTR_TAG_STR => {
+ if !self.extend_within(body_budget, 2)? {
+ return Ok(false);
+ }
+ let len_start = self.scratch.len() - 2;
+ let str_len =
+ u16::from_le_bytes([self.scratch[len_start], self.scratch[len_start + 1]])
+ as usize;
+ if str_len > MAX_ATTR_STR_BYTES {
+ return Ok(false);
+ }
+ str_len
+ }
+ ATTR_TAG_BOOL => 1,
+ ATTR_TAG_I64 | ATTR_TAG_F64 => 8,
+ _ => return Ok(false),
+ };
+ if !self.extend_within(body_budget, value_len)? {
+ return Ok(false);
+ }
+ if self.scratch.len() - attrs_start > MAX_ATTRS_TOTAL_BYTES {
+ return Ok(false);
+ }
+ }
+ Ok(true)
+ }
+
+ fn extend_within(&mut self, body_budget: u64, len: usize) -> Result<bool, VecDbError> {
+ if (self.scratch.len() + len) as u64 > body_budget {
+ return Ok(false);
+ }
+ self.fill_scratch(len)
+ }
+
+ fn fill_scratch(&mut self, len: usize) -> Result<bool, VecDbError> {
+ let old_len = self.scratch.len();
+ self.scratch.resize(old_len + len, 0);
+ match self.reader.read_exact(&mut self.scratch[old_len..]) {
+ Ok(()) => Ok(true),
+ Err(error) if error.kind() == ErrorKind::UnexpectedEof => {
+ self.scratch.truncate(old_len);
+ Ok(false)
+ }
+ Err(source) => {
+ self.done = true;
+ Err(VecDbError::io(self.path, source))
+ }
+ }
+ }
+
fn fill(&mut self, buffer: &mut [u8]) -> Result<bool, VecDbError> {
match self.reader.read_exact(buffer) {
Ok(()) => Ok(true),
@@ -331,6 +397,68 @@ impl LogScanner<'_> {
}
}
+fn decode_body(record_type: u8, key_len: usize, dims: usize, body: &[u8]) -> Option<LogRecord> {
+ let (key_bytes, rest) = body.split_at(key_len);
+ let key = std::str::from_utf8(key_bytes).ok()?.to_string();
+ if record_type == RECORD_TYPE_TOMBSTONE {
+ return Some(LogRecord::Tombstone { key });
+ }
+ let (payload, attr_bytes) = rest.split_at(dims * size_of::<f32>());
+ let vector = payload
+ .as_chunks::<4>()
+ .0
+ .iter()
+ .map(|bytes| f32::from_le_bytes(*bytes))
+ .collect();
+ let attrs = decode_attrs(attr_bytes)?;
+ Some(LogRecord::Add { key, vector, attrs })
+}
+
+fn decode_attrs(bytes: &[u8]) -> Option<Vec<Attribute>> {
+ let (&count, mut rest) = bytes.split_first()?;
+ let mut attrs = Vec::with_capacity(count as usize);
+ for _ in 0..count {
+ let (&name_len, after) = rest.split_first()?;
+ let (name_bytes, after) = after.split_at_checked(name_len as usize)?;
+ let name = std::str::from_utf8(name_bytes).ok()?.to_string();
+ let (&tag, after) = after.split_first()?;
+ let (value, after) = match tag {
+ ATTR_TAG_STR => {
+ let (len_bytes, after) = after.split_at_checked(2)?;
+ let str_len = u16::from_le_bytes([len_bytes[0], len_bytes[1]]) as usize;
+ let (value_bytes, after) = after.split_at_checked(str_len)?;
+ let value = std::str::from_utf8(value_bytes).ok()?.to_string();
+ (AttrValue::Str(value), after)
+ }
+ ATTR_TAG_BOOL => {
+ let (&value, after) = after.split_first()?;
+ if value > 1 {
+ return None;
+ }
+ (AttrValue::Bool(value == 1), after)
+ }
+ ATTR_TAG_I64 => {
+ let (value_bytes, after) = after.split_at_checked(8)?;
+ (
+ AttrValue::I64(i64::from_le_bytes(value_bytes.try_into().ok()?)),
+ after,
+ )
+ }
+ ATTR_TAG_F64 => {
+ let (value_bytes, after) = after.split_at_checked(8)?;
+ (
+ AttrValue::F64(f64::from_le_bytes(value_bytes.try_into().ok()?)),
+ after,
+ )
+ }
+ _ => return None,
+ };
+ attrs.push(Attribute { name, value });
+ rest = after;
+ }
+ rest.is_empty().then_some(attrs)
+}
+
fn encode_header(dims: u32, generation: &[u8; 16]) -> [u8; HEADER_LEN] {
let mut bytes = [0u8; HEADER_LEN];
bytes[0..4].copy_from_slice(&MAGIC);
@@ -397,7 +525,7 @@ fn validate_dims(dims: usize) -> Result<(), VecDbError> {
fn validate_entry(entry: &LogEntry<'_>, dims: usize) -> Result<(), VecDbError> {
match entry {
- LogEntry::Add { key, vector } => {
+ LogEntry::Add { key, vector, attrs } => {
validate_key(key)?;
if vector.len() != dims {
return Err(VecDbError::DimensionMismatch {
@@ -405,28 +533,116 @@ fn validate_entry(entry: &LogEntry<'_>, dims: usize) -> Result<(), VecDbError> {
actual: vector.len(),
});
}
- Ok(())
+ validate_attrs(attrs)
}
LogEntry::Tombstone { key } => validate_key(key),
}
}
+fn validate_attrs(attrs: &[Attribute]) -> Result<(), VecDbError> {
+ if attrs.len() > MAX_ATTR_COUNT {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "{} attributes, limit is {MAX_ATTR_COUNT}",
+ attrs.len()
+ )));
+ }
+ let mut total = 0usize;
+ for (index, attr) in attrs.iter().enumerate() {
+ if attr.name.is_empty() {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "attribute {index} has an empty name"
+ )));
+ }
+ if attr.name.len() > MAX_ATTR_NAME_BYTES {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "attribute name {:?} is {} bytes, limit is {MAX_ATTR_NAME_BYTES}",
+ attr.name,
+ attr.name.len()
+ )));
+ }
+ if let AttrValue::Str(value) = &attr.value
+ && value.len() > MAX_ATTR_STR_BYTES
+ {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "value of attribute {:?} is {} bytes, limit is {MAX_ATTR_STR_BYTES}",
+ attr.name,
+ value.len()
+ )));
+ }
+ if attrs[..index].iter().any(|prior| prior.name == attr.name) {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "duplicate attribute name {:?}",
+ attr.name
+ )));
+ }
+ total += encoded_attr_len(attr);
+ }
+ if total > MAX_ATTRS_TOTAL_BYTES {
+ return Err(VecDbError::InvalidAttributes(format!(
+ "attributes encode to {total} bytes, limit is {MAX_ATTRS_TOTAL_BYTES}"
+ )));
+ }
+ Ok(())
+}
+
+fn encoded_attr_len(attr: &Attribute) -> usize {
+ 2 + attr.name.len()
+ + match &attr.value {
+ AttrValue::Str(value) => 2 + value.len(),
+ AttrValue::Bool(_) => 1,
+ AttrValue::I64(_) | AttrValue::F64(_) => 8,
+ }
+}
+
fn encode_record_into(buffer: &mut Vec<u8>, entry: &LogEntry<'_>) {
- let (record_type, key, payload) = match entry {
- LogEntry::Add { key, vector } => (RECORD_TYPE_ADD, *key, *vector),
- LogEntry::Tombstone { key } => (RECORD_TYPE_TOMBSTONE, *key, &[] as &[f32]),
- };
let start = buffer.len();
- buffer.push(record_type);
- buffer.extend_from_slice(&(key.len() as u16).to_le_bytes());
- buffer.extend_from_slice(key.as_bytes());
- for value in payload {
- buffer.extend_from_slice(&value.to_le_bytes());
+ match entry {
+ LogEntry::Add { key, vector, attrs } => {
+ buffer.push(RECORD_TYPE_ADD);
+ buffer.extend_from_slice(&(key.len() as u16).to_le_bytes());
+ buffer.extend_from_slice(key.as_bytes());
+ for value in *vector {
+ buffer.extend_from_slice(&value.to_le_bytes());
+ }
+ buffer.push(attrs.len() as u8);
+ for attr in *attrs {
+ encode_attr_into(buffer, attr);
+ }
+ }
+ LogEntry::Tombstone { key } => {
+ buffer.push(RECORD_TYPE_TOMBSTONE);
+ buffer.extend_from_slice(&(key.len() as u16).to_le_bytes());
+ buffer.extend_from_slice(key.as_bytes());
+ }
}
let crc = crc32(&buffer[start..]);
buffer.extend_from_slice(&crc.to_le_bytes());
}
+fn encode_attr_into(buffer: &mut Vec<u8>, attr: &Attribute) {
+ buffer.push(attr.name.len() as u8);
+ buffer.extend_from_slice(attr.name.as_bytes());
+ match &attr.value {
+ AttrValue::Str(value) => {
+ buffer.push(ATTR_TAG_STR);
+ buffer.extend_from_slice(&(value.len() as u16).to_le_bytes());
+ buffer.extend_from_slice(value.as_bytes());
+ }
+ AttrValue::Bool(value) => {
+ buffer.push(ATTR_TAG_BOOL);
+ buffer.push(u8::from(*value));
+ }
+ AttrValue::I64(value) => {
+ buffer.push(ATTR_TAG_I64);
+ buffer.extend_from_slice(&value.to_le_bytes());
+ }
+ AttrValue::F64(value) => {
+ buffer.push(ATTR_TAG_F64);
+ buffer.extend_from_slice(&value.to_le_bytes());
+ }
+ }
+}
+
fn fresh_generation() -> [u8; 16] {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
@@ -521,7 +737,14 @@ mod tests {
fn encoded_add(key: &str, vector: &[f32]) -> Vec<u8> {
let mut bytes = Vec::new();
- encode_record_into(&mut bytes, &LogEntry::Add { key, vector });
+ encode_record_into(
+ &mut bytes,
+ &LogEntry::Add {
+ key,
+ vector,
+ attrs: &[],
+ },
+ );
bytes
}
@@ -536,9 +759,10 @@ mod tests {
fn expected_record(entry: &LogEntry<'_>) -> LogRecord {
match entry {
- LogEntry::Add { key, vector } => LogRecord::Add {
+ LogEntry::Add { key, vector, attrs } => LogRecord::Add {
key: (*key).to_string(),
vector: vector.to_vec(),
+ attrs: attrs.to_vec(),
},
LogEntry::Tombstone { key } => LogRecord::Tombstone {
key: (*key).to_string(),
@@ -682,6 +906,7 @@ mod tests {
&[LogEntry::Add {
key: "reborn",
vector: &vector,
+ attrs: &[],
}],
);
assert_eq!(start, HEADER_LEN as u64);
@@ -726,13 +951,39 @@ mod tests {
0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
0x56, 0x32, 0x6d, 0x51,
];
- let golden_add: [u8; 41] = [
+ let golden_add: [u8; 42] = [
0x01, 0x02, 0x00, 0x6b, 0x31, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x3f, 0x00,
0x00, 0x80, 0xbf, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0xbf, 0x00, 0x00, 0x00,
- 0x40, 0x00, 0x00, 0x00, 0xc0, 0x00, 0x00, 0xc0, 0x3f, 0x39, 0x42, 0xf6, 0x1d,
+ 0x40, 0x00, 0x00, 0x00, 0xc0, 0x00, 0x00, 0xc0, 0x3f, 0x00, 0xc7, 0x91, 0x1a, 0x8d,
+ ];
+ let golden_attr_add: [u8; 75] = [
+ 0x01, 0x02, 0x00, 0x6b, 0x32, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x3f, 0x00,
+ 0x00, 0x80, 0xbf, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0xbf, 0x00, 0x00, 0x00,
+ 0x40, 0x00, 0x00, 0x00, 0xc0, 0x00, 0x00, 0xc0, 0x3f, 0x04, 0x01, 0x6d, 0x00, 0x02,
+ 0x00, 0x76, 0x31, 0x01, 0x62, 0x01, 0x01, 0x01, 0x69, 0x02, 0xfe, 0xff, 0xff, 0xff,
+ 0xff, 0xff, 0xff, 0xff, 0x01, 0x66, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xf8,
+ 0x3f, 0x4a, 0x4a, 0x73, 0x96,
];
let golden_tombstone: [u8; 9] = [0x02, 0x02, 0x00, 0x6b, 0x31, 0xa0, 0xde, 0x3c, 0xc1];
let vector = [0.0f32, 1.0, -1.0, 0.5, -0.5, 2.0, -2.0, 1.5];
+ let attrs = vec![
+ Attribute {
+ name: "m".to_string(),
+ value: AttrValue::Str("v1".to_string()),
+ },
+ Attribute {
+ name: "b".to_string(),
+ value: AttrValue::Bool(true),
+ },
+ Attribute {
+ name: "i".to_string(),
+ value: AttrValue::I64(-2),
+ },
+ Attribute {
+ name: "f".to_string(),
+ value: AttrValue::F64(1.5),
+ },
+ ];
assert_eq!(encode_header(8, &generation), golden_header);
let mut encoded = Vec::new();
encode_record_into(
@@ -740,16 +991,28 @@ mod tests {
&LogEntry::Add {
key: "k1",
vector: &vector,
+ attrs: &[],
},
);
assert_eq!(encoded, golden_add);
encoded.clear();
+ encode_record_into(
+ &mut encoded,
+ &LogEntry::Add {
+ key: "k2",
+ vector: &vector,
+ attrs: &attrs,
+ },
+ );
+ assert_eq!(encoded, golden_attr_add);
+ encoded.clear();
encode_record_into(&mut encoded, &LogEntry::Tombstone { key: "k1" });
assert_eq!(encoded, golden_tombstone);
let dir = TempDir::new().unwrap();
let path = dir.path().join("log");
let mut bytes = golden_header.to_vec();
bytes.extend_from_slice(&golden_add);
+ bytes.extend_from_slice(&golden_attr_add);
bytes.extend_from_slice(&golden_tombstone);
std::fs::write(&path, &bytes).unwrap();
let mut log = reopen(&path, 8);
@@ -761,19 +1024,28 @@ mod tests {
(
LogRecord::Add {
key: "k1".to_string(),
- vector: vector.to_vec()
+ vector: vector.to_vec(),
+ attrs: Vec::new()
},
32
),
+ (
+ LogRecord::Add {
+ key: "k2".to_string(),
+ vector: vector.to_vec(),
+ attrs: attrs.clone()
+ },
+ 74
+ ),
(
LogRecord::Tombstone {
key: "k1".to_string()
},
- 73
+ 149
)
]
);
- assert_eq!(recoverable_end, 82);
+ assert_eq!(recoverable_end, 158);
}
#[test]
@@ -787,6 +1059,7 @@ mod tests {
LogEntry::Add {
key: "alpha",
vector: &vector,
+ attrs: &[],
},
LogEntry::Tombstone { key: "beta" },
];
@@ -826,6 +1099,7 @@ mod tests {
log.append(&[LogEntry::Add {
key,
vector: &vector,
+ attrs: &[],
}])
.unwrap();
log.append(&[LogEntry::Tombstone { key }]).unwrap();
@@ -837,7 +1111,8 @@ mod tests {
records[index * 2].0,
LogRecord::Add {
key: (*key).to_string(),
- vector: vector.clone()
+ vector: vector.clone(),
+ attrs: Vec::new()
}
);
assert_eq!(
@@ -867,12 +1142,14 @@ mod tests {
log.append(&[LogEntry::Add {
key: "weird",
vector: &vector,
+ attrs: &[],
}])
.unwrap();
let (records, _) = scan_all(&mut log);
let LogRecord::Add {
key,
vector: decoded,
+ ..
} = &records[0].0
else {
panic!("expected an add record");
@@ -894,7 +1171,11 @@ mod tests {
let key = format!("key-{index}");
boundaries.push(append_bounds(
&mut log,
- &[LogEntry::Add { key: &key, vector }],
+ &[LogEntry::Add {
+ key: &key,
+ vector,
+ attrs: &[],
+ }],
));
}
drop(log);
@@ -923,6 +1204,7 @@ mod tests {
&[LogEntry::Add {
key: "kept",
vector: &vector,
+ attrs: &[],
}],
);
let (_, torn_end) = append_bounds(
@@ -930,6 +1212,7 @@ mod tests {
&[LogEntry::Add {
key: "torn",
vector: &vector,
+ attrs: &[],
}],
);
drop(log);
@@ -950,6 +1233,7 @@ mod tests {
&[LogEntry::Add {
key: "fresh",
vector: &vector,
+ attrs: &[],
}],
);
assert_eq!(start, first_end);
@@ -971,6 +1255,7 @@ mod tests {
&[LogEntry::Add {
key: "acked",
vector: &vector,
+ attrs: &[],
}],
);
let phantom = encoded_add("phantom", &vector);
@@ -1000,6 +1285,7 @@ mod tests {
&[LogEntry::Add {
key: "kept",
vector: &vector,
+ attrs: &[],
}],
);
drop(log);
@@ -1008,7 +1294,8 @@ mod tests {
assert!(matches!(
log.append(&[LogEntry::Add {
key: "lost",
- vector: &vector
+ vector: &vector,
+ attrs: &[]
}]),
Err(VecDbError::Io { .. })
));
@@ -1032,6 +1319,7 @@ mod tests {
&[LogEntry::Add {
key: "first",
vector: &vector,
+ attrs: &[],
}],
);
append_raw_bytes(&path, &encoded_add("ghost", &vector));
@@ -1041,6 +1329,7 @@ mod tests {
&[LogEntry::Add {
key: "third",
vector: &replacement,
+ attrs: &[],
}],
);
assert_eq!(start, acked_end);
@@ -1071,7 +1360,11 @@ mod tests {
let key = format!("key-{index}");
boundaries.push(append_bounds(
&mut log,
- &[LogEntry::Add { key: &key, vector }],
+ &[LogEntry::Add {
+ key: &key,
+ vector,
+ attrs: &[],
+ }],
));
}
drop(log);
@@ -1107,6 +1400,7 @@ mod tests {
&LogEntry::Add {
key: "good",
vector: &vector,
+ attrs: &[],
},
);
let payload: Vec<u8> = vector
@@ -1151,6 +1445,7 @@ mod tests {
&[LogEntry::Add {
key: &key,
vector: &vector,
+ attrs: &[],
}],
);
assert_eq!(start, previous_end);
@@ -1178,14 +1473,16 @@ mod tests {
assert!(matches!(
log.append(&[LogEntry::Add {
key: "",
- vector: &vector
+ vector: &vector,
+ attrs: &[]
}]),
Err(VecDbError::InvalidKey(_))
));
assert!(matches!(
log.append(&[LogEntry::Add {
key: "ok",
- vector: &wrong_dims
+ vector: &wrong_dims,
+ attrs: &[]
}]),
Err(VecDbError::DimensionMismatch {
expected: 8,
@@ -1196,7 +1493,8 @@ mod tests {
log.append(&[
LogEntry::Add {
key: "good",
- vector: &vector
+ vector: &vector,
+ attrs: &[]
},
LogEntry::Tombstone { key: "" }
])
@@ -1250,7 +1548,11 @@ mod tests {
let entries: Vec<LogEntry<'_>> = keys
.iter()
.zip(&vectors)
- .map(|(key, vector)| LogEntry::Add { key, vector })
+ .map(|(key, vector)| LogEntry::Add {
+ key,
+ vector,
+ attrs: &[],
+ })
.collect();
let mut bulk_log = Log::create(&bulk_path, dims).unwrap();
let mut sequential_log = Log::create(&sequential_path, dims).unwrap();
@@ -1279,15 +1581,18 @@ mod tests {
LogEntry::Add {
key: "a",
vector: &vectors[0],
+ attrs: &[],
},
LogEntry::Tombstone { key: "b" },
LogEntry::Add {
key: "c",
vector: &vectors[2],
+ attrs: &[],
},
LogEntry::Add {
key: "d",
vector: &vectors[3],
+ attrs: &[],
},
];
let mut bulk_log = Log::create(&bulk_path, 8).unwrap();
@@ -1304,4 +1609,301 @@ mod tests {
assert_eq!(bulk_bytes[HEADER_LEN..], sequential_bytes[HEADER_LEN..]);
assert_eq!(scan_all(&mut bulk_log), scan_all(&mut sequential_log));
}
+
+ fn attr(name: &str, value: AttrValue) -> Attribute {
+ Attribute {
+ name: name.to_string(),
+ value,
+ }
+ }
+
+ fn scan_attrs_of_single_add(log: &mut Log) -> Vec<Attribute> {
+ let (records, _) = scan_all(log);
+ assert_eq!(records.len(), 1);
+ let LogRecord::Add { attrs, .. } = records[0].0.clone() else {
+ panic!("expected an add record");
+ };
+ attrs
+ }
+
+ #[test]
+ fn attr_records_round_trip_every_type_in_caller_order() {
+ let full_set = vec![
+ attr("zulu", AttrValue::I64(i64::MIN)),
+ attr("alpha", AttrValue::Str(String::new())),
+ attr("mike", AttrValue::Bool(false)),
+ attr("delta", AttrValue::F64(-0.0)),
+ ];
+ let singles: Vec<Vec<Attribute>> = vec![
+ vec![attr("s", AttrValue::Str("hΓ©llo-πŸ”‘".to_string()))],
+ vec![attr("b", AttrValue::Bool(true))],
+ vec![attr("i", AttrValue::I64(-1))],
+ vec![attr("f", AttrValue::F64(f64::MAX))],
+ Vec::new(),
+ ];
+ let dir = TempDir::new().unwrap();
+ let vector = seeded_vector(8, 8);
+ for (index, attrs) in singles.iter().chain([&full_set]).enumerate() {
+ let path = dir.path().join(format!("log-{index}"));
+ let mut log = Log::create(&path, 8).unwrap();
+ log.append(&[LogEntry::Add {
+ key: "k",
+ vector: &vector,
+ attrs,
+ }])
+ .unwrap();
+ assert_eq!(&scan_attrs_of_single_add(&mut log), attrs);
+ drop(log);
+ let mut reopened = reopen(&path, 8);
+ assert_eq!(&scan_attrs_of_single_add(&mut reopened), attrs);
+ }
+ }
+
+ #[test]
+ fn attr_boundary_sizes_round_trip() {
+ let cases = [
+ vec![attr(&"n".repeat(64), AttrValue::Bool(true))],
+ vec![attr("s", AttrValue::Str("v".repeat(1024)))],
+ (0..16)
+ .map(|index| attr(&format!("a{index:02}"), AttrValue::I64(index)))
+ .collect::<Vec<_>>(),
+ ["a", "b", "c", "d"]
+ .iter()
+ .map(|name| attr(name, AttrValue::Str("x".repeat(1019))))
+ .collect::<Vec<_>>(),
+ ];
+ assert_eq!(
+ cases[3].iter().map(encoded_attr_len).sum::<usize>(),
+ MAX_ATTRS_TOTAL_BYTES
+ );
+ let dir = TempDir::new().unwrap();
+ let vector = seeded_vector(9, 8);
+ for (index, attrs) in cases.iter().enumerate() {
+ let path = dir.path().join(format!("log-{index}"));
+ let mut log = Log::create(&path, 8).unwrap();
+ log.append(&[LogEntry::Add {
+ key: "k",
+ vector: &vector,
+ attrs,
+ }])
+ .unwrap();
+ assert_eq!(&scan_attrs_of_single_add(&mut log), attrs);
+ }
+ }
+
+ #[test]
+ fn append_rejects_attrs_beyond_the_caps() {
+ let over_total: Vec<Attribute> = ["a", "b", "c"]
+ .iter()
+ .map(|name| attr(name, AttrValue::Str("x".repeat(1019))))
+ .chain([attr("e", AttrValue::Str("x".repeat(1020)))])
+ .collect();
+ assert_eq!(
+ over_total.iter().map(encoded_attr_len).sum::<usize>(),
+ MAX_ATTRS_TOTAL_BYTES + 1
+ );
+ let invalid: Vec<Vec<Attribute>> = vec![
+ (0..17)
+ .map(|index| attr(&format!("a{index:02}"), AttrValue::Bool(true)))
+ .collect(),
+ vec![attr("", AttrValue::Bool(true))],
+ vec![attr(&"n".repeat(65), AttrValue::Bool(true))],
+ vec![attr("s", AttrValue::Str("v".repeat(1025)))],
+ over_total,
+ vec![
+ attr("same", AttrValue::Bool(true)),
+ attr("other", AttrValue::I64(1)),
+ attr("same", AttrValue::Str("again".to_string())),
+ ],
+ ];
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("log");
+ let mut log = Log::create(&path, 8).unwrap();
+ let vector = seeded_vector(10, 8);
+ for attrs in &invalid {
+ assert!(matches!(
+ log.append(&[LogEntry::Add {
+ key: "k",
+ vector: &vector,
+ attrs,
+ }]),
+ Err(VecDbError::InvalidAttributes(_))
+ ));
+ assert!(matches!(
+ log.append(&[
+ LogEntry::Add {
+ key: "good",
+ vector: &vector,
+ attrs: &[],
+ },
+ LogEntry::Add {
+ key: "bad",
+ vector: &vector,
+ attrs,
+ }
+ ]),
+ Err(VecDbError::InvalidAttributes(_))
+ ));
+ }
+ assert_eq!(log.current_end_offset(), HEADER_LEN as u64);
+ assert_eq!(std::fs::metadata(&path).unwrap().len(), HEADER_LEN as u64);
+ }
+
+ #[test]
+ fn non_finite_f64_attrs_round_trip_bit_exactly() {
+ let payloads = [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -0.0];
+ let attrs: Vec<Attribute> = payloads
+ .iter()
+ .enumerate()
+ .map(|(index, value)| attr(&format!("f{index}"), AttrValue::F64(*value)))
+ .collect();
+ let dir = TempDir::new().unwrap();
+ let mut log = Log::create(&dir.path().join("log"), 8).unwrap();
+ let vector = seeded_vector(11, 8);
+ log.append(&[LogEntry::Add {
+ key: "k",
+ vector: &vector,
+ attrs: &attrs,
+ }])
+ .unwrap();
+ let decoded = scan_attrs_of_single_add(&mut log);
+ assert_eq!(decoded.len(), payloads.len());
+ for (entry, expected) in decoded.iter().zip(&payloads) {
+ let AttrValue::F64(value) = entry.value else {
+ panic!("expected an f64 attribute");
+ };
+ assert_eq!(value.to_bits(), expected.to_bits());
+ }
+ }
+
+ #[test]
+ fn scanner_stops_at_malformed_attr_records() {
+ let dims = 8usize;
+ let vector = seeded_vector(12, dims);
+ let mut good = Vec::new();
+ encode_record_into(
+ &mut good,
+ &LogEntry::Add {
+ key: "good",
+ vector: &vector,
+ attrs: &[attr("kept", AttrValue::Bool(true))],
+ },
+ );
+ let vector_bytes: Vec<u8> = vector
+ .iter()
+ .flat_map(|value| value.to_le_bytes())
+ .collect();
+ let encoded_attr = |name: &[u8], tag: u8, value: &[u8]| {
+ let mut bytes = vec![name.len() as u8];
+ bytes.extend_from_slice(name);
+ bytes.push(tag);
+ bytes.extend_from_slice(value);
+ bytes
+ };
+ let str_value = |len: usize| {
+ let mut bytes = (len as u16).to_le_bytes().to_vec();
+ bytes.extend_from_slice(&vec![b'v'; len]);
+ bytes
+ };
+ let with_attrs = |attr_bytes: &[u8]| {
+ let mut payload = vector_bytes.clone();
+ payload.extend_from_slice(attr_bytes);
+ raw_record(RECORD_TYPE_ADD, 2, b"k1", &payload)
+ };
+ let five_over_total: Vec<u8> = {
+ let mut bytes = vec![5u8];
+ for name in [b"a", b"b", b"c", b"d", b"e"] {
+ bytes.extend_from_slice(&encoded_attr(name, ATTR_TAG_STR, &str_value(1019)));
+ }
+ bytes
+ };
+ let oversized_name: Vec<u8> = {
+ let mut bytes = vec![1u8];
+ bytes.extend_from_slice(&encoded_attr(&[b'n'; 65], ATTR_TAG_BOOL, &[1]));
+ bytes
+ };
+ let malformed = [
+ with_attrs(&[17]),
+ with_attrs(&[1, 0, ATTR_TAG_BOOL, 1]),
+ with_attrs(&oversized_name),
+ with_attrs(&{
+ let mut bytes = vec![1u8];
+ bytes.extend_from_slice(&encoded_attr(b"t", 4, &[0; 8]));
+ bytes
+ }),
+ with_attrs(&{
+ let mut bytes = vec![1u8];
+ bytes.extend_from_slice(&encoded_attr(b"s", ATTR_TAG_STR, &str_value(1025)));
+ bytes
+ }),
+ with_attrs(&{
+ let mut bytes = vec![1u8];
+ bytes.extend_from_slice(&encoded_attr(b"b", ATTR_TAG_BOOL, &[2]));
+ bytes
+ }),
+ with_attrs(&{
+ let mut bytes = vec![1u8];
+ bytes.extend_from_slice(&encoded_attr(&[0xFF, 0xFE], ATTR_TAG_BOOL, &[1]));
+ bytes
+ }),
+ with_attrs(&five_over_total),
+ with_attrs(&[2, 1, b'a', ATTR_TAG_BOOL, 1]),
+ with_attrs(&[1]),
+ ];
+ let dir = TempDir::new().unwrap();
+ for (index, bad) in malformed.iter().enumerate() {
+ let path = dir.path().join(format!("malformed-{index}"));
+ let mut record_bytes = good.clone();
+ record_bytes.extend_from_slice(bad);
+ write_log_file(&path, dims as u32, &record_bytes);
+ let mut log = reopen(&path, dims);
+ let (records, recoverable_end) = scan_all(&mut log);
+ assert_eq!(records.len(), 1, "case {index}");
+ assert_eq!(records[0].1, HEADER_LEN as u64, "case {index}");
+ assert_eq!(
+ recoverable_end,
+ HEADER_LEN as u64 + good.len() as u64,
+ "case {index}"
+ );
+ }
+ }
+
+ #[test]
+ fn scanner_stops_when_attrs_are_cut_by_the_log_end() {
+ let dims = 8usize;
+ let vector = seeded_vector(13, dims);
+ let mut good = Vec::new();
+ encode_record_into(
+ &mut good,
+ &LogEntry::Add {
+ key: "good",
+ vector: &vector,
+ attrs: &[],
+ },
+ );
+ let mut torn = Vec::new();
+ encode_record_into(
+ &mut torn,
+ &LogEntry::Add {
+ key: "torn",
+ vector: &vector,
+ attrs: &[
+ attr("first", AttrValue::Str("value".to_string())),
+ attr("second", AttrValue::I64(7)),
+ ],
+ },
+ );
+ let attrs_start = 3 + 4 + dims * size_of::<f32>();
+ let dir = TempDir::new().unwrap();
+ for cut in attrs_start..torn.len() {
+ let path = dir.path().join(format!("cut-{cut}"));
+ let mut record_bytes = good.clone();
+ record_bytes.extend_from_slice(&torn[..cut]);
+ write_log_file(&path, dims as u32, &record_bytes);
+ let mut log = reopen(&path, dims);
+ let (records, recoverable_end) = scan_all(&mut log);
+ assert_eq!(records.len(), 1, "cut {cut}");
+ assert_eq!(recoverable_end, HEADER_LEN as u64 + good.len() as u64);
+ }
+ }
}
diff --git a/rust/crates/ml/src/vecdb/mod.rs b/rust/crates/ml/src/vecdb/mod.rs
index bd30d89f27..a8a58d480a 100644
--- a/rust/crates/ml/src/vecdb/mod.rs
+++ b/rust/crates/ml/src/vecdb/mod.rs
@@ -13,6 +13,20 @@ mod store;
pub use store::{Stats, VecDb};
+#[derive(Debug, Clone, PartialEq)]
+pub enum AttrValue {
+ Str(String),
+ Bool(bool),
+ I64(i64),
+ F64(f64),
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct Attribute {
+ pub name: String,
+ pub value: AttrValue,
+}
+
#[derive(Debug, Clone, Default)]
pub struct SearchParams {
pub limit: Option<usize>,
@@ -53,6 +67,8 @@ pub enum VecDbError {
InvalidKey(String),
#[error("invalid vector: {0}")]
InvalidVector(String),
+ #[error("invalid attributes: {0}")]
+ InvalidAttributes(String),
#[error("dimension mismatch: expected {expected}, got {actual}")]
DimensionMismatch { expected: usize, actual: usize },
#[error("invalid dimensions {0}: must be a nonzero multiple of 8")]
diff --git a/rust/crates/ml/src/vecdb/store.rs b/rust/crates/ml/src/vecdb/store.rs
index 905e0b6aa2..386515f2bc 100644
--- a/rust/crates/ml/src/vecdb/store.rs
+++ b/rust/crates/ml/src/vecdb/store.rs
@@ -16,7 +16,7 @@ use super::log::{
sync_parent_dir,
};
use super::snapshot::{load_snapshot, remove_snapshot, snapshot_path, write_snapshot};
-use super::{KeyMatches, Match, SearchParams, VecDbError};
+use super::{AttrValue, Attribute, KeyMatches, Match, SearchParams, VecDbError};
const SNAPSHOT_HARD_CAP: usize = 5000;
const SNAPSHOT_QUIET_THRESHOLD: usize = 1000;
@@ -63,9 +63,69 @@ struct Shared {
struct SearchState {
arena: VectorArena,
graph: Graph,
+ attrs: AttrTable,
total_records: u64,
}
+#[derive(Default)]
+struct AttrTable(Option<Vec<Option<Box<[Attribute]>>>>);
+
+impl AttrTable {
+ fn set(&mut self, slot: u32, attrs: &[Attribute]) {
+ if attrs.is_empty() {
+ self.clear(slot);
+ return;
+ }
+ let table = self.0.get_or_insert_with(Vec::new);
+ let index = slot as usize;
+ if table.len() <= index {
+ table.resize_with(index + 1, || None);
+ }
+ table[index] = Some(attrs.to_vec().into_boxed_slice());
+ }
+
+ fn clear(&mut self, slot: u32) {
+ if let Some(table) = &mut self.0
+ && let Some(entry) = table.get_mut(slot as usize)
+ {
+ *entry = None;
+ }
+ }
+
+ fn get(&self, slot: u32) -> Option<&[Attribute]> {
+ self.0.as_ref()?.get(slot as usize)?.as_deref()
+ }
+
+ fn reset(&mut self) {
+ self.0 = None;
+ }
+
+ fn memory_bytes(&self) -> usize {
+ let Some(table) = &self.0 else {
+ return 0;
+ };
+ let mut bytes = table.capacity() * size_of::<Option<Box<[Attribute]>>>();
+ for entry in table.iter().flatten() {
+ bytes += entry.len() * size_of::<Attribute>();
+ for attr in entry.iter() {
+ bytes += attr.name.len();
+ if let AttrValue::Str(value) = &attr.value {
+ bytes += value.len();
+ }
+ }
+ }
+ bytes
+ }
+}
+
+fn slot_of_outcome(outcome: UpsertOutcome) -> u32 {
+ match outcome {
+ UpsertOutcome::NewSlot(slot)
+ | UpsertOutcome::RecycledSlot(slot)
+ | UpsertOutcome::ReplacedInPlace(slot) => slot,
+ }
+}
+
struct WriterHalf {
compaction_retry_at_dead: u64,
mode: WriterMode,
@@ -229,22 +289,60 @@ impl VecDb {
}
pub fn add(&self, key: &str, vector: &[f32]) -> Result<(), VecDbError> {
+ self.add_with_attrs(key, vector, &[])
+ }
+
+ pub fn add_with_attrs(
+ &self,
+ key: &str,
+ vector: &[f32],
+ attrs: &[Attribute],
+ ) -> Result<(), VecDbError> {
let now = Instant::now();
let mut half = self.writable_half()?;
let state = active_state(&mut half)?;
ensure_finite(key, vector)?;
- state.log.append(&[LogEntry::Add { key, vector }])?;
- apply_add(&self.shared, key, vector)?;
+ state.log.append(&[LogEntry::Add { key, vector, attrs }])?;
+ apply_add(&self.shared, key, vector, attrs)?;
apply_policy(&self.shared, &mut half, 1, now)
}
pub fn bulk_add(&self, keys: &[String], vectors: &[Vec<f32>]) -> Result<(), VecDbError> {
+ self.bulk_add_internal(keys, vectors, None)
+ }
+
+ pub fn bulk_add_with_attrs(
+ &self,
+ keys: &[String],
+ vectors: &[Vec<f32>],
+ attrs: &[Option<Vec<Attribute>>],
+ ) -> Result<(), VecDbError> {
+ if attrs.len() != keys.len() {
+ return Err(VecDbError::LengthMismatch {
+ keys: keys.len(),
+ vectors: attrs.len(),
+ });
+ }
+ self.bulk_add_internal(keys, vectors, Some(attrs))
+ }
+
+ fn bulk_add_internal(
+ &self,
+ keys: &[String],
+ vectors: &[Vec<f32>],
+ attrs: Option<&[Option<Vec<Attribute>>]>,
+ ) -> Result<(), VecDbError> {
if keys.len() != vectors.len() {
return Err(VecDbError::LengthMismatch {
keys: keys.len(),
vectors: vectors.len(),
});
}
+ let attrs_of = |index: usize| -> &[Attribute] {
+ attrs
+ .and_then(|entries| entries[index].as_deref())
+ .unwrap_or(&[])
+ };
let now = Instant::now();
let mut half = self.writable_half()?;
let state = active_state(&mut half)?;
@@ -257,11 +355,16 @@ impl VecDb {
let records: Vec<LogEntry<'_>> = keys
.iter()
.zip(vectors)
- .map(|(key, vector)| LogEntry::Add { key, vector })
+ .enumerate()
+ .map(|(index, (key, vector))| LogEntry::Add {
+ key,
+ vector,
+ attrs: attrs_of(index),
+ })
.collect();
state.log.append(&records)?;
- for (key, vector) in keys.iter().zip(vectors) {
- apply_add(&self.shared, key, vector)?;
+ for (index, (key, vector)) in keys.iter().zip(vectors).enumerate() {
+ apply_add(&self.shared, key, vector, attrs_of(index))?;
}
apply_policy(&self.shared, &mut half, keys.len(), now)
}
@@ -320,6 +423,22 @@ impl VecDb {
Some(st.arena.vector_values(slot))
}
+ pub fn get_attrs(&self, key: &str) -> Option<Vec<Attribute>> {
+ let st = self.shared.state_read();
+ let slot = st.arena.slot_of_key(key)?;
+ st.attrs.get(slot).map(<[Attribute]>::to_vec)
+ }
+
+ pub fn bulk_get_attrs(&self, keys: &[String]) -> Vec<Option<Vec<Attribute>>> {
+ let st = self.shared.state_read();
+ keys.iter()
+ .map(|key| {
+ let slot = st.arena.slot_of_key(key)?;
+ st.attrs.get(slot).map(<[Attribute]>::to_vec)
+ })
+ .collect()
+ }
+
pub fn search(&self, query: &[f32], params: &SearchParams) -> Result<Vec<Match>, VecDbError> {
self.shared.ensure_open()?;
if degenerate_distance_cut(params)? {
@@ -429,6 +548,7 @@ impl VecDb {
let mut st = self.shared.state_write();
st.arena = arena;
st.graph = Graph::new();
+ st.attrs.reset();
st.total_records = 0;
}
half.compaction_retry_at_dead = 0;
@@ -569,6 +689,7 @@ fn close_live_instance(shared: &Arc<Shared>) -> Result<(), VecDbError> {
if let Ok(empty) = VectorArena::new(shared.dims) {
st.arena = empty;
st.graph = Graph::new();
+ st.attrs.reset();
st.total_records = 0;
}
if let Some(key) = &shared.registry_key
@@ -585,14 +706,21 @@ fn close_live_instance(shared: &Arc<Shared>) -> Result<(), VecDbError> {
removed
}
-fn apply_add(shared: &Shared, key: &str, vector: &[f32]) -> Result<(), VecDbError> {
+fn apply_add(
+ shared: &Shared,
+ key: &str,
+ vector: &[f32],
+ attrs: &[Attribute],
+) -> Result<(), VecDbError> {
let mut st = shared.state_write();
let SearchState {
arena,
graph,
+ attrs: attr_table,
total_records,
} = &mut *st;
let outcome = arena.upsert(key, vector)?;
+ attr_table.set(slot_of_outcome(outcome), attrs);
apply_outcome(graph, arena, outcome);
*total_records += 1;
Ok(())
@@ -600,7 +728,9 @@ fn apply_add(shared: &Shared, key: &str, vector: &[f32]) -> Result<(), VecDbErro
fn apply_remove(shared: &Shared, key: &str) {
let mut st = shared.state_write();
- st.arena.remove(key);
+ if let Some(slot) = st.arena.remove(key) {
+ st.attrs.clear(slot);
+ }
st.total_records += 1;
}
@@ -665,9 +795,10 @@ fn compact(shared: &Shared, half: &mut WriterHalf) -> Result<(), VecDbError> {
let dims = shared.dims;
let (mut temp_log, temp_path) = Log::create_temp_sibling(&shared.path, dims)?;
let mut compacted = VectorArena::new(dims)?;
+ let mut compacted_attrs = AttrTable::default();
let staged = {
let st = shared.state_read();
- stage_live_entries(&st.arena, &mut compacted, &mut temp_log)
+ stage_live_entries(&st, &mut compacted, &mut compacted_attrs, &mut temp_log)
};
if let Err(error) = staged {
drop(temp_log);
@@ -697,6 +828,7 @@ fn compact(shared: &Shared, half: &mut WriterHalf) -> Result<(), VecDbError> {
let mut st = shared.state_write();
st.arena = compacted;
st.graph = graph;
+ st.attrs = compacted_attrs;
st.total_records = total_records;
}
let restored = restore_writer_mode(shared, half, lock, last_write);
@@ -750,6 +882,7 @@ fn recover_after_failed_reset(
let mut st = shared.state_write();
st.arena = empty;
st.graph = Graph::new();
+ st.attrs.reset();
st.total_records = 0;
half.compaction_retry_at_dead = 0;
}
@@ -812,6 +945,7 @@ fn build_writer(path: &Path, registry_key: PathBuf, dims: usize) -> Result<Share
state: RwLock::new(SearchState {
arena: replayed.arena,
graph: replayed.graph,
+ attrs: replayed.attrs,
total_records: replayed.total_records,
}),
})
@@ -840,6 +974,7 @@ fn build_read_only(path: &Path, dims: usize) -> Result<Shared, VecDbError> {
dims,
replayed.arena,
replayed.graph,
+ replayed.attrs,
replayed.total_records,
replayed.recoverable_end,
))
@@ -851,6 +986,7 @@ fn empty_read_only(path: &Path, dims: usize) -> Result<Shared, VecDbError> {
dims,
VectorArena::new(dims)?,
Graph::new(),
+ AttrTable::default(),
0,
0,
))
@@ -861,6 +997,7 @@ fn read_only_shared(
dims: usize,
arena: VectorArena,
graph: Graph,
+ attrs: AttrTable,
total_records: u64,
log_bytes: u64,
) -> Shared {
@@ -876,6 +1013,7 @@ fn read_only_shared(
state: RwLock::new(SearchState {
arena,
graph,
+ attrs,
total_records,
}),
}
@@ -907,12 +1045,13 @@ fn approximate_memory_bytes(state: &SearchState) -> usize {
.sum::<usize>()
})
.sum();
- vector_bytes + key_bytes + free_list_bytes + graph_bytes
+ vector_bytes + key_bytes + free_list_bytes + graph_bytes + state.attrs.memory_bytes()
}
struct ReplayedState {
arena: VectorArena,
graph: Graph,
+ attrs: AttrTable,
total_records: u64,
recoverable_end: u64,
used_snapshot: bool,
@@ -925,6 +1064,7 @@ fn replay(log: &mut Log, dims: usize) -> Result<ReplayedState, VecDbError> {
.as_ref()
.map_or(u64::MAX, |loaded| loaded.covered_log_offset);
let mut arena = VectorArena::new(dims)?;
+ let mut attrs = AttrTable::default();
let mut tail_outcomes: Vec<UpsertOutcome> = Vec::new();
let mut tail_records = 0u64;
let mut total_records = 0u64;
@@ -940,14 +1080,21 @@ fn replay(log: &mut Log, dims: usize) -> Result<ReplayedState, VecDbError> {
tail_records += 1;
}
match record {
- LogRecord::Add { key, vector } => {
+ LogRecord::Add {
+ key,
+ vector,
+ attrs: record_attrs,
+ } => {
let outcome = arena.upsert(&key, &vector)?;
+ attrs.set(slot_of_outcome(outcome), &record_attrs);
if in_tail {
tail_outcomes.push(outcome);
}
}
LogRecord::Tombstone { key } => {
- arena.remove(&key);
+ if let Some(slot) = arena.remove(&key) {
+ attrs.clear(slot);
+ }
}
}
}
@@ -974,6 +1121,7 @@ fn replay(log: &mut Log, dims: usize) -> Result<ReplayedState, VecDbError> {
Ok(ReplayedState {
arena,
graph,
+ attrs,
total_records,
recoverable_end,
used_snapshot,
@@ -1025,26 +1173,37 @@ fn remove_data_files(path: &Path) -> Result<(), VecDbError> {
}
fn stage_live_entries(
- source: &VectorArena,
+ source: &SearchState,
target: &mut VectorArena,
+ target_attrs: &mut AttrTable,
log: &mut Log,
) -> Result<(), VecDbError> {
- let mut batch: Vec<(String, Vec<f32>)> = Vec::with_capacity(COMPACTION_BATCH_SIZE);
- for slot in source.live_slots() {
- let Some(key) = source.key_of_slot(slot) else {
+ let mut batch: Vec<(String, Vec<f32>, Vec<Attribute>)> =
+ Vec::with_capacity(COMPACTION_BATCH_SIZE);
+ for slot in source.arena.live_slots() {
+ let Some(key) = source.arena.key_of_slot(slot) else {
continue;
};
- batch.push((key.to_string(), source.vector_values(slot)));
+ batch.push((
+ key.to_string(),
+ source.arena.vector_values(slot),
+ source
+ .attrs
+ .get(slot)
+ .map(<[Attribute]>::to_vec)
+ .unwrap_or_default(),
+ ));
if batch.len() == COMPACTION_BATCH_SIZE {
- flush_stage_batch(&mut batch, target, log)?;
+ flush_stage_batch(&mut batch, target, target_attrs, log)?;
}
}
- flush_stage_batch(&mut batch, target, log)
+ flush_stage_batch(&mut batch, target, target_attrs, log)
}
fn flush_stage_batch(
- batch: &mut Vec<(String, Vec<f32>)>,
+ batch: &mut Vec<(String, Vec<f32>, Vec<Attribute>)>,
target: &mut VectorArena,
+ target_attrs: &mut AttrTable,
log: &mut Log,
) -> Result<(), VecDbError> {
if batch.is_empty() {
@@ -1052,11 +1211,12 @@ fn flush_stage_batch(
}
let records: Vec<LogEntry<'_>> = batch
.iter()
- .map(|(key, vector)| LogEntry::Add { key, vector })
+ .map(|(key, vector, attrs)| LogEntry::Add { key, vector, attrs })
.collect();
log.append(&records)?;
- for (key, vector) in batch.drain(..) {
- target.upsert(&key, &vector)?;
+ for (key, vector, attrs) in batch.drain(..) {
+ let outcome = target.upsert(&key, &vector)?;
+ target_attrs.set(slot_of_outcome(outcome), &attrs);
}
Ok(())
}
@@ -1073,7 +1233,7 @@ mod tests {
use super::*;
const DIMS: usize = 16;
- const ADD_RECORD_LEN: u64 = 3 + 5 + (DIMS as u64) * 4 + 4;
+ const ADD_RECORD_LEN: u64 = 3 + 5 + (DIMS as u64) * 4 + 1 + 4;
const TOMBSTONE_RECORD_LEN: u64 = 3 + 5 + 4;
fn seeded_unit_vector(seed: u64, dims: usize) -> Vec<f32> {
@@ -2915,4 +3075,295 @@ mod tests {
fresh.add("fresh", &seeded_unit_vector(3, DIMS)).unwrap();
assert_eq!(fresh.len(), 1);
}
+
+ fn attr(name: &str, value: AttrValue) -> Attribute {
+ Attribute {
+ name: name.to_string(),
+ value,
+ }
+ }
+
+ fn sample_attrs(seed: i64) -> Vec<Attribute> {
+ vec![
+ attr("model", AttrValue::Str(format!("model-{seed}"))),
+ attr("version", AttrValue::I64(seed)),
+ attr("indexed", AttrValue::Bool(seed % 2 == 0)),
+ attr("score", AttrValue::F64(seed as f64 * 0.5)),
+ ]
+ }
+
+ #[test]
+ fn attrs_round_trip_and_upserts_replace_them_wholesale() {
+ let dir = TempDir::new().unwrap();
+ let db = open_writer(&dir.path().join("db"));
+ let vector = seeded_unit_vector(1, DIMS);
+ db.add_with_attrs("k", &vector, &sample_attrs(1)).unwrap();
+ assert_eq!(db.get_attrs("k").unwrap(), sample_attrs(1));
+ assert_eq!(db.get("k").unwrap(), vector);
+ db.add_with_attrs("k", &vector, &[attr("only", AttrValue::Bool(true))])
+ .unwrap();
+ assert_eq!(
+ db.get_attrs("k").unwrap(),
+ vec![attr("only", AttrValue::Bool(true))]
+ );
+ db.add("k", &vector).unwrap();
+ assert_eq!(db.get_attrs("k"), None);
+ db.add_with_attrs("k", &vector, &sample_attrs(2)).unwrap();
+ assert_eq!(db.get_attrs("k").unwrap(), sample_attrs(2));
+ db.add_with_attrs("k", &vector, &[]).unwrap();
+ assert_eq!(db.get_attrs("k"), None);
+ db.add("plain", &vector).unwrap();
+ assert_eq!(db.get_attrs("plain"), None);
+ assert_eq!(db.get_attrs("missing"), None);
+ assert!(matches!(
+ db.add_with_attrs(
+ "k",
+ &vector,
+ &[
+ attr("dup", AttrValue::Bool(true)),
+ attr("dup", AttrValue::Bool(false))
+ ]
+ ),
+ Err(VecDbError::InvalidAttributes(_))
+ ));
+ }
+
+ #[test]
+ fn attrs_do_not_leak_across_remove_and_slot_recycle() {
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("db");
+ let db = open_writer(&path);
+ let vector = seeded_unit_vector(2, DIMS);
+ db.add_with_attrs("a", &vector, &sample_attrs(10)).unwrap();
+ db.add_with_attrs("b", &vector, &sample_attrs(11)).unwrap();
+ assert!(db.remove("a").unwrap());
+ assert_eq!(db.get_attrs("a"), None);
+ db.add("c", &vector).unwrap();
+ assert_eq!(db.shared.state_read().arena.slot_of_key("c"), Some(0));
+ assert_eq!(db.get_attrs("c"), None);
+ assert!(db.remove("b").unwrap());
+ db.add_with_attrs("d", &vector, &sample_attrs(12)).unwrap();
+ assert_eq!(db.shared.state_read().arena.slot_of_key("d"), Some(1));
+ assert_eq!(db.get_attrs("d").unwrap(), sample_attrs(12));
+ db.add("a", &vector).unwrap();
+ assert_eq!(db.get_attrs("a"), None);
+ drop(db);
+ let reopened = open_writer(&path);
+ assert_eq!(reopened.get_attrs("a"), None);
+ assert_eq!(reopened.get_attrs("b"), None);
+ assert_eq!(reopened.get_attrs("c"), None);
+ assert_eq!(reopened.get_attrs("d").unwrap(), sample_attrs(12));
+ }
+
+ #[test]
+ fn attrs_replay_identically_across_reopen_and_read_only() {
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("db");
+ let db = open_writer(&path);
+ let vector = seeded_unit_vector(3, DIMS);
+ let ordered = vec![
+ attr("zulu", AttrValue::I64(-5)),
+ attr("alpha", AttrValue::Str("first".to_string())),
+ attr("mike", AttrValue::F64(2.25)),
+ ];
+ db.add("plain", &vector).unwrap();
+ db.add_with_attrs("rich", &vector, &ordered).unwrap();
+ db.add_with_attrs("cleared", &vector, &sample_attrs(20))
+ .unwrap();
+ db.add("cleared", &vector).unwrap();
+ db.add_with_attrs("removed", &vector, &sample_attrs(21))
+ .unwrap();
+ assert!(db.remove("removed").unwrap());
+ db.add_with_attrs("recycled", &vector, &sample_attrs(22))
+ .unwrap();
+ db.flush().unwrap();
+ drop(db);
+ let verify = |db: &VecDb| {
+ assert_eq!(db.get_attrs("plain"), None);
+ assert_eq!(db.get_attrs("rich").unwrap(), ordered);
+ assert_eq!(db.get_attrs("cleared"), None);
+ assert_eq!(db.get_attrs("removed"), None);
+ assert_eq!(db.get_attrs("recycled").unwrap(), sample_attrs(22));
+ };
+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();
+ verify(&read_only);
+ drop(read_only);
+ let reopened = open_writer(&path);
+ verify(&reopened);
+ drop(reopened);
+ fs::remove_file(snapshot_path(&path)).unwrap();
+ let rebuilt = open_writer(&path);
+ verify(&rebuilt);
+ }
+
+ #[test]
+ fn attrs_follow_entries_through_compaction() {
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("db");
+ let db = open_writer(&path);
+ let entries = bulk_entries(0, 120, 640);
+ let (keys, vectors): (Vec<String>, Vec<Vec<f32>>) = entries.iter().cloned().unzip();
+ let attrs: Vec<Option<Vec<Attribute>>> = (0..120)
+ .map(|index| (index % 2 == 0).then(|| sample_attrs(index)))
+ .collect();
+ db.bulk_add_with_attrs(&keys, &vectors, &attrs).unwrap();
+ let removals: Vec<String> = (0..64).map(|index| format!("key-{index}")).collect();
+ assert_eq!(db.bulk_remove(&removals).unwrap(), 64);
+ assert_eq!(db.stats().unwrap().dead_count, 0);
+ let verify = |db: &VecDb| {
+ for index in 64..120i64 {
+ let key = format!("key-{index}");
+ if index % 2 == 0 {
+ assert_eq!(db.get_attrs(&key).unwrap(), sample_attrs(index));
+ } else {
+ assert_eq!(db.get_attrs(&key), None);
+ }
+ }
+ for index in 0..64 {
+ assert_eq!(db.get_attrs(&format!("key-{index}")), None);
+ }
+ };
+ verify(&db);
+ drop(db);
+ let reopened = open_writer(&path);
+ verify(&reopened);
+ }
+
+ #[test]
+ fn attrs_survive_a_failed_compaction_and_its_retry() {
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("db");
+ let db = open_writer(&path);
+ let entries = bulk_entries(0, 120, 910);
+ let (keys, vectors): (Vec<String>, Vec<Vec<f32>>) = entries.iter().cloned().unzip();
+ let attrs: Vec<Option<Vec<Attribute>>> =
+ (0..120).map(|index| Some(sample_attrs(index))).collect();
+ db.bulk_add_with_attrs(&keys, &vectors, &attrs).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();
+ assert_eq!(db.bulk_remove(&removals).unwrap(), 64);
+ assert_eq!(db.stats().unwrap().dead_count, 128);
+ assert_eq!(generation_of(&path), generation_before);
+ let verify = |db: &VecDb| {
+ for index in 64..120i64 {
+ assert_eq!(
+ db.get_attrs(&format!("key-{index}")).unwrap(),
+ sample_attrs(index)
+ );
+ }
+ for index in 0..64 {
+ assert_eq!(db.get_attrs(&format!("key-{index}")), None);
+ }
+ };
+ verify(&db);
+ fs::remove_dir(temp_sibling(&path)).unwrap();
+ let rewrite = |range: std::ops::Range<usize>| {
+ let (keys, vectors): (Vec<String>, Vec<Vec<f32>>) =
+ bulk_entries(range.start, range.len(), 910)
+ .iter()
+ .cloned()
+ .unzip();
+ let attrs: Vec<Option<Vec<Attribute>>> = range
+ .map(|index| Some(sample_attrs(index as i64)))
+ .collect();
+ db.bulk_add_with_attrs(&keys, &vectors, &attrs).unwrap();
+ };
+ rewrite(64..120);
+ assert_eq!(db.stats().unwrap().dead_count, 184);
+ assert_eq!(generation_of(&path), generation_before);
+ verify(&db);
+ rewrite(64..72);
+ assert_eq!(db.stats().unwrap().dead_count, 0);
+ assert_ne!(generation_of(&path), generation_before);
+ verify(&db);
+ drop(db);
+ let reopened = open_writer(&path);
+ verify(&reopened);
+ }
+
+ #[test]
+ fn bulk_attrs_validate_before_any_io() {
+ let dir = TempDir::new().unwrap();
+ let path = dir.path().join("db");
+ let db = open_writer(&path);
+ let vector = seeded_unit_vector(5, DIMS);
+ db.add("seed", &vector).unwrap();
+ let log_bytes = db.stats().unwrap().log_bytes;
+ let keys = vec!["x".to_string(), "y".to_string()];
+ let vectors = vec![vector.clone(), vector.clone()];
+ assert!(matches!(
+ db.bulk_add_with_attrs(&keys, &vectors, &[None]),
+ Err(VecDbError::LengthMismatch {
+ keys: 2,
+ vectors: 1
+ })
+ ));
+ let poisoned = vec![
+ Some(sample_attrs(1)),
+ Some(vec![
+ attr("dup", AttrValue::Bool(true)),
+ attr("dup", AttrValue::Bool(false)),
+ ]),
+ ];
+ assert!(matches!(
+ db.bulk_add_with_attrs(&keys, &vectors, &poisoned),
+ Err(VecDbError::InvalidAttributes(_))
+ ));
+ assert_eq!(db.len(), 1);
+ assert!(!db.contains("x"));
+ assert_eq!(db.stats().unwrap().log_bytes, log_bytes);
+ let valid = vec![Some(sample_attrs(7)), None];
+ db.bulk_add_with_attrs(&keys, &vectors, &valid).unwrap();
+ assert_eq!(
+ db.bulk_get_attrs(&[
+ "x".to_string(),
+ "missing".to_string(),
+ "y".to_string(),
+ "seed".to_string()
+ ]),
+ vec![Some(sample_attrs(7)), None, None, None]
+ );
+ assert_eq!(db.get_attrs("x").unwrap(), sample_attrs(7));
+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();
+ assert!(matches!(
+ read_only.bulk_add_with_attrs(&keys, &vectors, &[None]),
+ Err(VecDbError::LengthMismatch { .. })
+ ));
+ assert!(matches!(
+ read_only.bulk_add_with_attrs(&keys, &vectors, &valid),
+ Err(VecDbError::ReadOnly)
+ ));
+ }
+
+ #[test]
+ fn reset_clears_attrs() {
+ let dir = TempDir::new().unwrap();
+ let db = open_writer(&dir.path().join("db"));
+ let vector = seeded_unit_vector(6, DIMS);
+ db.add_with_attrs("k", &vector, &sample_attrs(30)).unwrap();
+ db.reset().unwrap();
+ assert_eq!(db.get_attrs("k"), None);
+ db.add("k", &vector).unwrap();
+ assert_eq!(db.get_attrs("k"), None);
+ db.add_with_attrs("k", &vector, &sample_attrs(31)).unwrap();
+ assert_eq!(db.get_attrs("k").unwrap(), sample_attrs(31));
+ }
+
+ #[test]
+ fn memory_estimate_counts_the_attr_table_once_allocated() {
+ let dir = TempDir::new().unwrap();
+ let db = open_writer(&dir.path().join("db"));
+ let vector = seeded_unit_vector(7, DIMS);
+ db.add("k", &vector).unwrap();
+ let without_attrs = db.stats().unwrap().approximate_memory_bytes;
+ db.add_with_attrs(
+ "k",
+ &vector,
+ &[attr("blob", AttrValue::Str("x".repeat(512)))],
+ )
+ .unwrap();
+ let with_attrs = db.stats().unwrap().approximate_memory_bytes;
+ assert!(with_attrs > without_attrs + 512);
+ }
}