vectlite 0.9.0 → 0.9.1

package/native/vectlite-core/src/lib.rs

@@ -14,6 +14,7 @@ use simsimd::SpatialSimilarity;
 
 use quantization::{
     MultiVectorQuantizationConfig, MultiVectorQuantizedIndex, QuantizationConfig, QuantizedIndex,
+    valid_product_num_sub_vectors, validate_quantization_config,
 };
 
 const MAGIC: &[u8; 4] = b"VDB1";
@@ -233,7 +234,10 @@ fn scalar_manhattan_distance(left: &[f32], right: &[f32]) -> f32 {
 #[derive(Clone, Debug)]
 enum WalOp {
     Upsert(Record),
-    Delete { namespace: String, id: String },
+    Delete {
+        namespace: String,
+        id: String,
+    },
     UpdateMetadata {
         namespace: String,
         id: String,
@@ -1147,7 +1151,10 @@ impl NumericIndex {
     /// Return keys where value > threshold.
     fn range_gt(&self, threshold: f64) -> HashSet<RecordKey> {
         let mut result = HashSet::new();
-        for (_, set) in self.tree.range((std::ops::Bound::Excluded(OrdF64(threshold)), std::ops::Bound::Unbounded)) {
+        for (_, set) in self.tree.range((
+            std::ops::Bound::Excluded(OrdF64(threshold)),
+            std::ops::Bound::Unbounded,
+        )) {
             result.extend(set.iter().cloned());
         }
         result
@@ -1255,9 +1262,9 @@ impl AnnHnsw {
             AnnHnsw::DotProduct(h) => h.file_dump(directory, basename),
             AnnHnsw::Manhattan(h) => h.file_dump(directory, basename),
         };
-        result
-            .map(|_| ())
-            .map_err(|err| VectLiteError::InvalidFormat(format!("failed to persist ANN index: {err}")))
+        result.map(|_| ()).map_err(|err| {
+            VectLiteError::InvalidFormat(format!("failed to persist ANN index: {err}"))
+        })
     }
 }
 
@@ -1514,9 +1521,7 @@ impl Database {
                 .filter_map(|key| self.records.get(key))
                 .filter(|record| {
                     !record.is_expired_at(now)
-                        && filter
-                            .map(|f| f.matches(&record.metadata))
-                            .unwrap_or(true)
+                        && filter.map(|f| f.matches(&record.metadata)).unwrap_or(true)
                 })
                 .count()
         } else {
@@ -1563,9 +1568,7 @@ impl Database {
                 .filter_map(|key| self.records.get(*key))
                 .filter(|record| {
                     !record.is_expired_at(now)
-                        && filter
-                            .map(|f| f.matches(&record.metadata))
-                            .unwrap_or(true)
+                        && filter.map(|f| f.matches(&record.metadata)).unwrap_or(true)
                 })
                 .skip(offset)
                 .take(if limit == 0 { usize::MAX } else { limit })
@@ -1659,9 +1662,7 @@ impl Database {
 
         let next_cursor = if results.len() > limit {
             results.pop(); // remove the extra
-            results
-                .last()
-                .map(|r| format!("{}\0{}", r.namespace, r.id))
+            results.last().map(|r| format!("{}\0{}", r.namespace, r.id))
         } else {
             None
         };
@@ -1710,11 +1711,7 @@ impl Database {
     ///
     /// Returns `true` if the record exists and was updated, `false` if the
     /// record was not found (no error is raised).
-    pub fn update_metadata(
-        &mut self,
-        id: impl Into<String>,
-        metadata: Metadata,
-    ) -> Result<bool> {
+    pub fn update_metadata(&mut self, id: impl Into<String>, metadata: Metadata) -> Result<bool> {
         self.update_metadata_in_namespace(DEFAULT_NAMESPACE, id, metadata)
     }
 
@@ -1841,7 +1838,11 @@ impl Database {
             PayloadIndexType::Numeric => {
                 let mut num = NumericIndex::default();
                 for (key, record) in &self.records {
-                    if let Some(val) = record.metadata.get(&field).and_then(MetadataValue::as_number) {
+                    if let Some(val) = record
+                        .metadata
+                        .get(&field)
+                        .and_then(MetadataValue::as_number)
+                    {
                         num.insert(val, key.clone());
                     }
                 }
@@ -2290,6 +2291,18 @@ impl Database {
                 "search requires a dense query, a sparse query, or both".to_owned(),
             ));
         }
+        // Reject zero-norm query vectors for metrics where similarity is undefined.
+        if let Some(query) = dense_query {
+            if self.metric.is_similarity() {
+                let norm_sq: f32 = query.iter().map(|v| v * v).sum();
+                if norm_sq == 0.0 {
+                    return Err(VectLiteError::InvalidFormat(
+                        "query vector has zero norm; cosine/dot-product similarity is undefined"
+                            .to_owned(),
+                    ));
+                }
+            }
+        }
         if let Some(mmr_lambda) = options.mmr_lambda {
             if !(0.0..=1.0).contains(&mmr_lambda) {
                 return Err(VectLiteError::InvalidFormat(
@@ -2326,14 +2339,13 @@ impl Database {
         let dense_start = Instant::now();
         // Use quantized index for candidate selection if available (2-stage pipeline).
         // The quantized index operates on the default vector only and globally (not per-namespace).
-        let quantized_candidates =
-            if !matryoshka_truncated
-                && (vector_name.is_none() || vector_name == Some(DEFAULT_VECTOR_NAME))
-            {
-                dense_query.and_then(|query| self.quantized_candidate_keys(query, fetch_k))
-            } else {
-                None
-            };
+        let quantized_candidates = if !matryoshka_truncated
+            && (vector_name.is_none() || vector_name == Some(DEFAULT_VECTOR_NAME))
+        {
+            dense_query.and_then(|query| self.quantized_candidate_keys(query, fetch_k))
+        } else {
+            None
+        };
         let ann_candidates = if quantized_candidates.is_some() {
             // Skip HNSW if quantized index provided candidates
             None
@@ -2363,13 +2375,18 @@ impl Database {
         };
 
         // Use payload indexes to narrow candidates when doing a full scan.
-        let payload_candidates = options.filter.as_ref().and_then(|f| {
-            self.payload_index_candidates(f, namespace)
-        });
+        let payload_candidates = options
+            .filter
+            .as_ref()
+            .and_then(|f| self.payload_index_candidates(f, namespace));
         let candidate_keys = match (candidate_keys, payload_candidates) {
             (Some(ck), Some(pc)) => {
                 // Intersect ANN/sparse candidates with payload index candidates.
-                Some(ck.into_iter().filter(|k| pc.contains(k)).collect::<Vec<_>>())
+                Some(
+                    ck.into_iter()
+                        .filter(|k| pc.contains(k))
+                        .collect::<Vec<_>>(),
+                )
             }
             (None, Some(pc)) => {
                 // No ANN candidates but payload index narrowed the set.
@@ -2403,8 +2420,14 @@ impl Database {
 
         if effective_dense_candidates.is_some() && results.len() < fetch_k {
             stats.exact_fallback = true;
-            results =
-                self.collect_results(dense_query, sparse_query, &options, namespace, None, effective_dimension);
+            results = self.collect_results(
+                dense_query,
+                sparse_query,
+                &options,
+                namespace,
+                None,
+                effective_dimension,
+            );
             stats.considered_count = results.len();
         }
 
@@ -2522,6 +2545,7 @@ impl Database {
                 "cannot enable quantization on an empty database".to_owned(),
             ));
         }
+        validate_quantization_config(&config, self.dimension)?;
         self.quantization_config = Some(config);
         self.rebuild_quantized_index();
         self.persist_quantization_params()?;
@@ -2552,6 +2576,11 @@ impl Database {
         self.quantization_config.as_ref()
     }
 
+    /// Returns all valid Product Quantization `num_sub_vectors` values for this database.
+    pub fn valid_num_sub_vectors(&self) -> Vec<usize> {
+        valid_product_num_sub_vectors(self.dimension)
+    }
+
     /// Rebuild the quantized index from current records.
     fn rebuild_quantized_index(&mut self) {
         let config = match &self.quantization_config {
@@ -2635,7 +2664,7 @@ impl Database {
             return None;
         }
 
-        let candidate_indices = index.search_candidates(query, top_k);
+        let candidate_indices = index.search_candidates_with_metric(query, top_k, self.metric);
         Some(
             candidate_indices
                 .into_iter()
@@ -2657,7 +2686,11 @@ impl Database {
         multi_vectors: MultiVectors,
     ) -> Result<()> {
         self.upsert_multi_vectors_in_namespace(
-            DEFAULT_NAMESPACE, id, vector, metadata, multi_vectors,
+            DEFAULT_NAMESPACE,
+            id,
+            vector,
+            metadata,
+            multi_vectors,
         )
     }
 
@@ -2716,10 +2749,8 @@ impl Database {
 
         // Try quantized multi-vector search first for candidate selection
         let query_refs: Vec<&[f32]> = query_tokens.iter().map(Vec::as_slice).collect();
-        let candidate_keys: Option<Vec<RecordKey>> = self
-            .multi_vector_quantized
-            .get(space)
-            .and_then(|index| {
+        let candidate_keys: Option<Vec<RecordKey>> =
+            self.multi_vector_quantized.get(space).and_then(|index| {
                 let keys = self.multi_vector_quantized_keys.get(space)?;
                 let candidate_indices = index.search(&query_refs, top_k);
                 Some(
@@ -2740,9 +2771,7 @@ impl Database {
         let mut scored: Vec<(f32, &Record)> = record_iter
             .filter(|record| {
                 !record.is_expired_at(now)
-                    && namespace
-                        .map(|ns| record.namespace == ns)
-                        .unwrap_or(true)
+                    && namespace.map(|ns| record.namespace == ns).unwrap_or(true)
                     && record.multi_vectors.contains_key(space)
                     && options
                         .filter
@@ -2840,14 +2869,9 @@ impl Database {
             return;
         }
 
-        let index = MultiVectorQuantizedIndex::build(
-            &doc_token_vectors,
-            token_dimension,
-            &config,
-        );
+        let index = MultiVectorQuantizedIndex::build(&doc_token_vectors, token_dimension, &config);
 
-        self.multi_vector_quantized
-            .insert(space.to_owned(), index);
+        self.multi_vector_quantized.insert(space.to_owned(), index);
         self.multi_vector_quantized_keys
             .insert(space.to_owned(), keys);
     }
@@ -2928,15 +2952,15 @@ impl Database {
 
             if !doc_token_vectors.is_empty() {
                 index.rebuild(&doc_token_vectors);
-                let MultiVectorQuantizationConfig::TwoBit(ref cfg) = {
-                    MultiVectorQuantizationConfig::TwoBit(index.quantizer.config.clone())
-                };
-                self.multi_vector_quantization_config
-                    .insert(space.to_owned(), MultiVectorQuantizationConfig::TwoBit(cfg.clone()));
+                let MultiVectorQuantizationConfig::TwoBit(ref cfg) =
+                    { MultiVectorQuantizationConfig::TwoBit(index.quantizer.config.clone()) };
+                self.multi_vector_quantization_config.insert(
+                    space.to_owned(),
+                    MultiVectorQuantizationConfig::TwoBit(cfg.clone()),
+                );
                 self.multi_vector_quantized_keys
                     .insert(space.to_owned(), keys);
-                self.multi_vector_quantized
-                    .insert(space.to_owned(), index);
+                self.multi_vector_quantized.insert(space.to_owned(), index);
             }
         }
     }
@@ -3020,7 +3044,11 @@ impl Database {
                 PayloadIndexType::Numeric => {
                     let mut num = NumericIndex::default();
                     for (key, record) in &self.records {
-                        if let Some(val) = record.metadata.get(field).and_then(MetadataValue::as_number) {
+                        if let Some(val) = record
+                            .metadata
+                            .get(field)
+                            .and_then(MetadataValue::as_number)
+                        {
                             num.insert(val, key.clone());
                         }
                     }
@@ -3071,14 +3099,22 @@ impl Database {
     /// Use payload indexes to narrow down candidate keys for a filter.
     /// Returns `None` if no indexes can help with this filter (fallback to scan).
     /// Returns `Some(set)` with the set of record keys that *may* match the filter.
-    fn payload_index_candidates(&self, filter: &MetadataFilter, namespace: Option<&str>) -> Option<HashSet<RecordKey>> {
+    fn payload_index_candidates(
+        &self,
+        filter: &MetadataFilter,
+        namespace: Option<&str>,
+    ) -> Option<HashSet<RecordKey>> {
         if self.payload_indexes.is_empty() {
             return None;
         }
         self.payload_index_candidates_inner(filter, namespace)
     }
 
-    fn payload_index_candidates_inner(&self, filter: &MetadataFilter, namespace: Option<&str>) -> Option<HashSet<RecordKey>> {
+    fn payload_index_candidates_inner(
+        &self,
+        filter: &MetadataFilter,
+        namespace: Option<&str>,
+    ) -> Option<HashSet<RecordKey>> {
         match filter {
             MetadataFilter::Eq { key, value } => {
                 // Try keyword index for string equality
@@ -3172,7 +3208,11 @@ impl Database {
         }
     }
 
-    fn filter_by_namespace(&self, keys: HashSet<RecordKey>, namespace: Option<&str>) -> HashSet<RecordKey> {
+    fn filter_by_namespace(
+        &self,
+        keys: HashSet<RecordKey>,
+        namespace: Option<&str>,
+    ) -> HashSet<RecordKey> {
         match namespace {
             Some(ns) => keys.into_iter().filter(|(n, _)| n == ns).collect(),
             None => keys,
@@ -3357,7 +3397,9 @@ impl Database {
             WalOp::UpdateMetadata { .. } | WalOp::SetTtl { .. } => false,
         });
 
-        let metadata_only = ops.iter().all(|op| matches!(op, WalOp::UpdateMetadata { .. } | WalOp::SetTtl { .. }));
+        let metadata_only = ops
+            .iter()
+            .all(|op| matches!(op, WalOp::UpdateMetadata { .. } | WalOp::SetTtl { .. }));
 
         self.append_wal_batch(&ops)?;
         self.apply_ops_in_memory(ops);
@@ -3721,22 +3763,32 @@ impl Database {
             Some(0) => {
                 return Err(VectLiteError::InvalidFormat(
                     "truncate_dim must be greater than zero".to_owned(),
-                ))
+                ));
             }
             Some(dim) if dim > self.dimension => {
                 return Err(VectLiteError::DimensionMismatch {
                     expected: self.dimension,
                     found: dim,
-                })
+                });
             }
             Some(dim) if dim > query.len() => {
                 return Err(VectLiteError::InvalidFormat(format!(
                     "truncate_dim ({dim}) cannot exceed query vector length ({})",
                     query.len()
-                )))
+                )));
             }
             Some(dim) => dim,
-            None => query.len(),
+            None => {
+                // Without explicit truncate_dim, require exact dimension match.
+                // Users must pass truncate_dim to opt into Matryoshka truncation.
+                if query.len() != self.dimension {
+                    return Err(VectLiteError::DimensionMismatch {
+                        expected: self.dimension,
+                        found: query.len(),
+                    });
+                }
+                query.len()
+            }
         };
 
         Ok(Some(effective))
@@ -4058,8 +4110,13 @@ impl Database {
                         let mut weighted_sum = 0.0_f32;
                         for (name, (query, weight)) in &options.multi_vector_queries {
                             if let Some(vector) = record.vector_for(Some(name.as_str())) {
-                                weighted_sum +=
-                                    weight * score_dense_prefix(self.metric, query, vector, effective_dimension);
+                                weighted_sum += weight
+                                    * score_dense_prefix(
+                                        self.metric,
+                                        query,
+                                        vector,
+                                        effective_dimension,
+                                    );
                             }
                         }
                         (weighted_sum, None)
@@ -4375,11 +4432,7 @@ fn ensure_dimension(dimension: usize) -> Result<()> {
 /// MaxSim scoring (ColBERT-style late interaction).
 /// For each query token, find the maximum similarity against any document
 /// token using the given metric, then sum those maxima across all query tokens.
-fn maxsim_score(
-    query_tokens: &[&[f32]],
-    doc_tokens: &[Vec<f32>],
-    metric: DistanceMetric,
-) -> f32 {
+fn maxsim_score(query_tokens: &[&[f32]], doc_tokens: &[Vec<f32>], metric: DistanceMetric) -> f32 {
     if query_tokens.is_empty() || doc_tokens.is_empty() {
         return 0.0;
     }
@@ -4428,8 +4481,13 @@ fn build_ann_index(records: Vec<(RecordKey, &Vec<f32>)>, metric: DistanceMetric)
 
     macro_rules! build_hnsw {
         ($dist_type:ty, $dist_val:expr, $variant:ident) => {{
-            let mut hnsw =
-                Hnsw::<f32, $dist_type>::new(ANN_M, count, max_layer, ANN_EF_CONSTRUCTION, $dist_val);
+            let mut hnsw = Hnsw::<f32, $dist_type>::new(
+                ANN_M,
+                count,
+                max_layer,
+                ANN_EF_CONSTRUCTION,
+                $dist_val,
+            );
             let mut keys = Vec::with_capacity(count);
             for (origin_id, (key, vector)) in records.into_iter().enumerate() {
                 hnsw.insert((vector.as_slice(), origin_id));
@@ -4616,11 +4674,13 @@ fn ann_basename(path: &Path, namespace: Option<&str>, vector_name: &str) -> Stri
         .file_name()
         .and_then(|name| name.to_str())
         .unwrap_or("vectlite");
-    format!(
-        "{stem}.ann.{}.{}",
-        hex_encode(namespace.unwrap_or(DEFAULT_NAMESPACE).as_bytes()),
-        hex_encode(vector_name.as_bytes())
-    )
+    let ns_hex = hex_encode(namespace.unwrap_or(DEFAULT_NAMESPACE).as_bytes());
+    let vn_hex = hex_encode(vector_name.as_bytes());
+    // Use "_" sentinel for empty components to avoid triple-dot filenames
+    // like "c.vdb.ann...hnsw.data".
+    let ns_part = if ns_hex.is_empty() { "_" } else { &ns_hex };
+    let vn_part = if vn_hex.is_empty() { "_" } else { &vn_hex };
+    format!("{stem}.ann.{ns_part}.{vn_part}")
 }
 
 fn hex_encode(bytes: &[u8]) -> String {
@@ -5350,9 +5410,9 @@ fn usize_from_u64(value: u64) -> Result<usize> {
 #[cfg(test)]
 mod tests {
     use super::{
-        Database, HybridSearchOptions, Metadata, MetadataFilter, MetadataValue, MultiVectors,
-        MultiVectorSearchOptions, NamedVectors, PayloadIndexType, Record, SearchOptions,
-        SparseVector, VectLiteError,
+        Database, DistanceMetric, HybridSearchOptions, Metadata, MetadataFilter, MetadataValue,
+        MultiVectorSearchOptions, MultiVectors, NamedVectors, PayloadIndexType, Record,
+        SearchOptions, SparseVector, VectLiteError,
     };
     use std::path::{Path, PathBuf};
     use std::time::{SystemTime, UNIX_EPOCH};
@@ -6046,6 +6106,54 @@ mod tests {
         cleanup(&path);
     }
 
+    #[test]
+    fn scalar_quantization_keeps_signed_cosine_neighbor_in_candidate_set() {
+        use super::quantization::{QuantizationConfig, ScalarQuantizationConfig};
+
+        let path = temp_file("quant-scalar-signed-recall");
+        let dim = 146;
+
+        let mut query = vec![-1.0_f32; dim];
+        for value in &mut query[..10] {
+            *value = 1.0;
+        }
+
+        let mut db = Database::create(&path, dim).expect("create");
+        for i in 0..120 {
+            db.upsert(format!("high{i:03}"), vec![2.0_f32; dim], Metadata::new())
+                .expect("upsert high distractor");
+        }
+
+        let mut calibration_low = vec![2.0_f32; dim];
+        for value in &mut calibration_low[..10] {
+            *value = -1.0;
+        }
+        db.upsert("calibration-low", calibration_low, Metadata::new())
+            .expect("upsert calibration low");
+        db.upsert("target", query.clone(), Metadata::new())
+            .expect("upsert target");
+
+        db.enable_quantization(QuantizationConfig::Scalar(ScalarQuantizationConfig {
+            rescore_multiplier: 1,
+        }))
+        .expect("enable quant");
+
+        let results = db
+            .search(
+                &query,
+                SearchOptions {
+                    top_k: 1,
+                    filter: None,
+                    truncate_dim: None,
+                },
+            )
+            .expect("search");
+
+        assert_eq!(results[0].id, "target");
+
+        cleanup(&path);
+    }
+
     #[test]
     fn binary_quantization_enables_search() {
         use super::quantization::{BinaryQuantizationConfig, QuantizationConfig};
@@ -6187,6 +6295,40 @@ mod tests {
         cleanup(&path);
     }
 
+    #[test]
+    fn product_quantization_invalid_subvector_count_returns_error() {
+        use super::quantization::{ProductQuantizationConfig, QuantizationConfig};
+
+        let path = temp_file("quant-pq-invalid-subvectors");
+        let mut db = Database::create(&path, 146).expect("create");
+        for i in 0..4 {
+            db.upsert(
+                format!("doc{i}"),
+                vec![0.1_f32 + i as f32; 146],
+                Metadata::new(),
+            )
+            .expect("upsert");
+        }
+        assert_eq!(db.valid_num_sub_vectors(), vec![1, 2, 73, 146]);
+
+        let result =
+            db.enable_quantization(QuantizationConfig::Product(ProductQuantizationConfig {
+                num_sub_vectors: 16,
+                num_centroids: 4,
+                training_iterations: 1,
+                rescore_multiplier: 1,
+            }));
+
+        assert!(matches!(
+            result,
+            Err(VectLiteError::InvalidFormat(message))
+                if message.contains("dimension (146) must be divisible by num_sub_vectors (16)")
+        ));
+        assert!(!db.is_quantized());
+
+        cleanup(&path);
+    }
+
     // -----------------------------------------------------------------------
     // Multi-vector / ColBERT-style integration tests
     // -----------------------------------------------------------------------
@@ -6200,10 +6342,7 @@ mod tests {
         let mut mv1 = MultiVectors::new();
         mv1.insert(
             "colbert".to_owned(),
-            vec![
-                vec![1.0, 0.0, 0.0],
-                vec![0.0, 1.0, 0.0],
-            ],
+            vec![vec![1.0, 0.0, 0.0], vec![0.0, 1.0, 0.0]],
         );
         db.upsert_multi_vectors("doc1", vec![1.0, 0.0, 0.0], Metadata::new(), mv1)
             .expect("upsert doc1");
@@ -6211,10 +6350,7 @@ mod tests {
         let mut mv2 = MultiVectors::new();
         mv2.insert(
             "colbert".to_owned(),
-            vec![
-                vec![0.0, 0.0, 1.0],
-                vec![0.0, 1.0, 0.0],
-            ],
+            vec![vec![0.0, 0.0, 1.0], vec![0.0, 1.0, 0.0]],
         );
         db.upsert_multi_vectors("doc2", vec![0.0, 0.0, 1.0], Metadata::new(), mv2)
             .expect("upsert doc2");
@@ -6222,13 +6358,14 @@ mod tests {
         assert_eq!(db.len(), 2);
 
         // Search with query tokens that strongly match doc1
-        let query_tokens = vec![
-            vec![1.0, 0.0, 0.0],
-            vec![0.0, 1.0, 0.0],
-        ];
+        let query_tokens = vec![vec![1.0, 0.0, 0.0], vec![0.0, 1.0, 0.0]];
 
         let results = db
-            .search_multi_vector("colbert", &query_tokens, MultiVectorSearchOptions::default())
+            .search_multi_vector(
+                "colbert",
+                &query_tokens,
+                MultiVectorSearchOptions::default(),
+            )
             .expect("search");
 
         assert_eq!(results.len(), 2);
@@ -6255,7 +6392,11 @@ mod tests {
         let db = Database::create(&path, 3).expect("create");
 
         let query_tokens: Vec<Vec<f32>> = vec![];
-        let result = db.search_multi_vector("colbert", &query_tokens, MultiVectorSearchOptions::default());
+        let result = db.search_multi_vector(
+            "colbert",
+            &query_tokens,
+            MultiVectorSearchOptions::default(),
+        );
         assert!(result.is_err());
 
         cleanup(&path);
@@ -6268,10 +6409,22 @@ mod tests {
 
         let mut mv = MultiVectors::new();
         mv.insert("colbert".to_owned(), vec![vec![1.0, 0.0, 0.0]]);
-        db.upsert_multi_vectors_in_namespace("ns1", "doc1", vec![1.0, 0.0, 0.0], Metadata::new(), mv.clone())
-            .expect("upsert ns1");
-        db.upsert_multi_vectors_in_namespace("ns2", "doc2", vec![0.0, 1.0, 0.0], Metadata::new(), mv.clone())
-            .expect("upsert ns2");
+        db.upsert_multi_vectors_in_namespace(
+            "ns1",
+            "doc1",
+            vec![1.0, 0.0, 0.0],
+            Metadata::new(),
+            mv.clone(),
+        )
+        .expect("upsert ns1");
+        db.upsert_multi_vectors_in_namespace(
+            "ns2",
+            "doc2",
+            vec![0.0, 1.0, 0.0],
+            Metadata::new(),
+            mv.clone(),
+        )
+        .expect("upsert ns2");
 
         let query_tokens = vec![vec![1.0, 0.0, 0.0]];
         let options = MultiVectorSearchOptions {
@@ -6279,7 +6432,9 @@ mod tests {
             filter: None,
             namespace: Some("ns1".to_owned()),
         };
-        let results = db.search_multi_vector("colbert", &query_tokens, options).expect("search");
+        let results = db
+            .search_multi_vector("colbert", &query_tokens, options)
+            .expect("search");
 
         assert_eq!(results.len(), 1);
         assert_eq!(results[0].id, "doc1");
@@ -6331,13 +6486,18 @@ mod tests {
         // Search should still work
         let query_tokens = vec![vec![9.0, 0.0, 0.0], vec![0.0, 9.0, 0.0]];
         let results = db
-            .search_multi_vector("colbert", &query_tokens, MultiVectorSearchOptions::default())
+            .search_multi_vector(
+                "colbert",
+                &query_tokens,
+                MultiVectorSearchOptions::default(),
+            )
             .expect("search");
 
         assert!(!results.is_empty());
 
         // Disable quantization
-        db.disable_multi_vector_quantization("colbert").expect("disable");
+        db.disable_multi_vector_quantization("colbert")
+            .expect("disable");
         assert!(!db.is_multi_vector_quantized("colbert"));
 
         cleanup(&path);
@@ -6387,7 +6547,11 @@ mod tests {
         // Search should work on reopened database
         let query_tokens = vec![vec![0.9, 0.5, 0.5]];
         let results = db
-            .search_multi_vector("colbert", &query_tokens, MultiVectorSearchOptions::default())
+            .search_multi_vector(
+                "colbert",
+                &query_tokens,
+                MultiVectorSearchOptions::default(),
+            )
             .expect("search");
         assert!(!results.is_empty());
 
@@ -6421,7 +6585,7 @@ mod tests {
 
     #[test]
     fn multi_vector_maxsim_scoring_correctness() {
-        use super::{maxsim_score, DistanceMetric};
+        use super::{DistanceMetric, maxsim_score};
 
         // Two identical sets: MaxSim should be sum of 1.0 per query token
         let query = [&[1.0_f32, 0.0, 0.0][..], &[0.0, 1.0, 0.0]];
@@ -6479,17 +6643,44 @@ mod tests {
     fn distance_metric_name_aliases() {
         use super::DistanceMetric;
         // Euclidean aliases
-        assert_eq!(DistanceMetric::from_name("l2").unwrap(), DistanceMetric::Euclidean);
-        assert_eq!(DistanceMetric::from_name("L2").unwrap(), DistanceMetric::Euclidean);
-        assert_eq!(DistanceMetric::from_name("EUCLIDEAN").unwrap(), DistanceMetric::Euclidean);
+        assert_eq!(
+            DistanceMetric::from_name("l2").unwrap(),
+            DistanceMetric::Euclidean
+        );
+        assert_eq!(
+            DistanceMetric::from_name("L2").unwrap(),
+            DistanceMetric::Euclidean
+        );
+        assert_eq!(
+            DistanceMetric::from_name("EUCLIDEAN").unwrap(),
+            DistanceMetric::Euclidean
+        );
         // DotProduct aliases
-        assert_eq!(DistanceMetric::from_name("dot").unwrap(), DistanceMetric::DotProduct);
-        assert_eq!(DistanceMetric::from_name("dot_product").unwrap(), DistanceMetric::DotProduct);
-        assert_eq!(DistanceMetric::from_name("ip").unwrap(), DistanceMetric::DotProduct);
-        assert_eq!(DistanceMetric::from_name("inner_product").unwrap(), DistanceMetric::DotProduct);
+        assert_eq!(
+            DistanceMetric::from_name("dot").unwrap(),
+            DistanceMetric::DotProduct
+        );
+        assert_eq!(
+            DistanceMetric::from_name("dot_product").unwrap(),
+            DistanceMetric::DotProduct
+        );
+        assert_eq!(
+            DistanceMetric::from_name("ip").unwrap(),
+            DistanceMetric::DotProduct
+        );
+        assert_eq!(
+            DistanceMetric::from_name("inner_product").unwrap(),
+            DistanceMetric::DotProduct
+        );
         // Manhattan aliases
-        assert_eq!(DistanceMetric::from_name("l1").unwrap(), DistanceMetric::Manhattan);
-        assert_eq!(DistanceMetric::from_name("L1").unwrap(), DistanceMetric::Manhattan);
+        assert_eq!(
+            DistanceMetric::from_name("l1").unwrap(),
+            DistanceMetric::Manhattan
+        );
+        assert_eq!(
+            DistanceMetric::from_name("L1").unwrap(),
+            DistanceMetric::Manhattan
+        );
         // Invalid
         assert!(DistanceMetric::from_name("hamming").is_err());
     }
@@ -6634,8 +6825,8 @@ mod tests {
     fn search_with_euclidean_metric() {
         use super::DistanceMetric;
         let path = temp_file("metric-search-euclidean");
-        let mut db = Database::create_with_metric(&path, 3, DistanceMetric::Euclidean)
-            .expect("create");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::Euclidean).expect("create");
 
         // Insert vectors at known distances from query [0, 0, 0]
         db.insert("close", vec![1.0, 0.0, 0.0], Metadata::new())
@@ -6671,8 +6862,8 @@ mod tests {
     fn search_with_dotproduct_metric() {
         use super::DistanceMetric;
         let path = temp_file("metric-search-dot");
-        let mut db = Database::create_with_metric(&path, 3, DistanceMetric::DotProduct)
-            .expect("create");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::DotProduct).expect("create");
 
         // Vectors with different dot products with query [1, 0, 0]
         db.insert("high", vec![10.0, 0.0, 0.0], Metadata::new())
@@ -6707,8 +6898,8 @@ mod tests {
     fn search_with_manhattan_metric() {
         use super::DistanceMetric;
         let path = temp_file("metric-search-manhattan");
-        let mut db = Database::create_with_metric(&path, 3, DistanceMetric::Manhattan)
-            .expect("create");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::Manhattan).expect("create");
 
         // Vectors at known Manhattan distances from query [0, 0, 0]
         db.insert("close", vec![1.0, 0.0, 0.0], Metadata::new())
@@ -6755,6 +6946,7 @@ mod tests {
                 None,
                 HybridSearchOptions {
                     top_k: 2,
+                    truncate_dim: Some(2),
                     ..HybridSearchOptions::default()
                 },
             )
@@ -6801,8 +6993,8 @@ mod tests {
     fn search_with_cosine_metric_explicit() {
         use super::DistanceMetric;
         let path = temp_file("metric-search-cosine-explicit");
-        let mut db = Database::create_with_metric(&path, 3, DistanceMetric::Cosine)
-            .expect("create");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::Cosine).expect("create");
 
         db.insert("aligned", vec![2.0, 0.0, 0.0], Metadata::new())
             .expect("insert aligned"); // cosine = 1.0
@@ -6836,8 +7028,8 @@ mod tests {
         use super::DistanceMetric;
         let path = temp_file("metric-upsert-cycle");
         {
-            let mut db = Database::create_with_metric(&path, 3, DistanceMetric::Manhattan)
-                .expect("create");
+            let mut db =
+                Database::create_with_metric(&path, 3, DistanceMetric::Manhattan).expect("create");
             db.upsert("a", vec![1.0, 0.0, 0.0], Metadata::new())
                 .expect("upsert a");
             db.upsert("b", vec![0.0, 5.0, 0.0], Metadata::new())
@@ -6916,7 +7108,8 @@ mod tests {
         let mut meta = Metadata::new();
         meta.insert("source".into(), "blog".into());
         meta.insert("version".into(), MetadataValue::Integer(1));
-        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+            .expect("upsert");
 
         // Patch: update version, add new key
         let mut patch = Metadata::new();
@@ -6966,7 +7159,8 @@ mod tests {
 
         let mut meta = Metadata::new();
         meta.insert("source".into(), "blog".into());
-        db.upsert("doc1", vec![1.0, 2.0, 3.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 2.0, 3.0], meta)
+            .expect("upsert");
 
         let mut patch = Metadata::new();
         patch.insert("source".into(), "updated".into());
@@ -6986,7 +7180,8 @@ mod tests {
             let mut db = Database::create(&path, 3).expect("create");
             let mut meta = Metadata::new();
             meta.insert("source".into(), "blog".into());
-            db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+            db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+                .expect("upsert");
 
             let mut patch = Metadata::new();
             patch.insert("source".into(), "updated".into());
@@ -7052,7 +7247,8 @@ mod tests {
 
         let mut meta = Metadata::new();
         meta.insert("status".into(), "draft".into());
-        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+            .expect("upsert");
 
         // Before patch: filter matches
         let count = db.count_filtered(None, Some(&MetadataFilter::eq("status", "draft")));
@@ -7320,7 +7516,8 @@ mod tests {
 
             let mut meta = Metadata::new();
             meta.insert("source".into(), "blog".into());
-            db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+            db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+                .expect("upsert");
 
             let mut meta2 = Metadata::new();
             meta2.insert("source".into(), "docs".into());
@@ -7356,7 +7553,8 @@ mod tests {
         // Now upsert records — they should be indexed incrementally
         let mut meta = Metadata::new();
         meta.insert("source".into(), "blog".into());
-        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+            .expect("upsert");
 
         let count = db.count_filtered(None, Some(&MetadataFilter::eq("source", "blog")));
         assert_eq!(count, 1);
@@ -7381,7 +7579,8 @@ mod tests {
 
         let mut meta = Metadata::new();
         meta.insert("source".into(), "blog".into());
-        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+            .expect("upsert");
 
         let mut meta2 = Metadata::new();
         meta2.insert("source".into(), "blog".into());
@@ -7454,7 +7653,8 @@ mod tests {
 
         let mut meta = Metadata::new();
         meta.insert("status".into(), "draft".into());
-        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta).expect("upsert");
+        db.upsert("doc1", vec![1.0, 0.0, 0.0], meta)
+            .expect("upsert");
 
         db.create_index("status", PayloadIndexType::Keyword)
             .expect("create");
@@ -7490,7 +7690,10 @@ mod tests {
         // Insert records with source and priority
         for i in 0..30 {
             let mut meta = Metadata::new();
-            meta.insert("source".into(), if i % 2 == 0 { "blog" } else { "docs" }.into());
+            meta.insert(
+                "source".into(),
+                if i % 2 == 0 { "blog" } else { "docs" }.into(),
+            );
             meta.insert("priority".into(), MetadataValue::Float((i % 3) as f64));
             db.upsert(format!("doc{}", i), vec![1.0, 0.0, 0.0], meta)
                 .expect("upsert");
@@ -7659,7 +7862,10 @@ mod tests {
 
         for i in 0..20 {
             let mut meta = Metadata::new();
-            meta.insert("type".into(), if i % 2 == 0 { "even" } else { "odd" }.into());
+            meta.insert(
+                "type".into(),
+                if i % 2 == 0 { "even" } else { "odd" }.into(),
+            );
             db.upsert(format!("doc{}", i), vec![1.0, 0.0, 0.0], meta)
                 .expect("upsert");
         }
@@ -7929,7 +8135,10 @@ mod tests {
         assert!(db.get_in_namespace("ns1", "doc1").is_none());
 
         // Wrong namespace returns false
-        assert!(!db.set_ttl_in_namespace("ns2", "doc1", 60.0).expect("set wrong ns"));
+        assert!(
+            !db.set_ttl_in_namespace("ns2", "doc1", 60.0)
+                .expect("set wrong ns")
+        );
 
         cleanup(&path);
     }
@@ -7943,12 +8152,8 @@ mod tests {
         let path = temp_file("cursor-basic");
         let mut db = Database::create(&path, 3).expect("create");
         for i in 0..5 {
-            db.upsert(
-                &format!("doc{i}"),
-                vec![1.0, 0.0, 0.0],
-                Metadata::new(),
-            )
-            .expect("upsert");
+            db.upsert(&format!("doc{i}"), vec![1.0, 0.0, 0.0], Metadata::new())
+                .expect("upsert");
         }
 
         // First page of 2
@@ -7983,12 +8188,22 @@ mod tests {
         let path = temp_file("cursor-ns");
         let mut db = Database::create(&path, 3).expect("create");
         for i in 0..3 {
-            db.upsert_in_namespace("ns1", &format!("doc{i}"), vec![1.0, 0.0, 0.0], Metadata::new())
-                .expect("upsert");
+            db.upsert_in_namespace(
+                "ns1",
+                &format!("doc{i}"),
+                vec![1.0, 0.0, 0.0],
+                Metadata::new(),
+            )
+            .expect("upsert");
         }
         for i in 0..2 {
-            db.upsert_in_namespace("ns2", &format!("doc{i}"), vec![0.0, 1.0, 0.0], Metadata::new())
-                .expect("upsert");
+            db.upsert_in_namespace(
+                "ns2",
+                &format!("doc{i}"),
+                vec![0.0, 1.0, 0.0],
+                Metadata::new(),
+            )
+            .expect("upsert");
         }
 
         let (page1, cursor1) = db.list_cursor(Some("ns1"), None, 2, None);
@@ -8007,12 +8222,8 @@ mod tests {
         let path = temp_file("cursor-ttl");
         let mut db = Database::create(&path, 3).expect("create");
         for i in 0..5 {
-            db.upsert(
-                &format!("doc{i}"),
-                vec![1.0, 0.0, 0.0],
-                Metadata::new(),
-            )
-            .expect("upsert");
+            db.upsert(&format!("doc{i}"), vec![1.0, 0.0, 0.0], Metadata::new())
+                .expect("upsert");
         }
 
         // Expire doc1
@@ -8045,4 +8256,153 @@ mod tests {
         assert!(cursor.is_none());
         cleanup(&path);
     }
+
+    // ---------------------------------------------------------------
+    // Bug #14: zero-norm query vector should be rejected for cosine
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn search_zero_norm_query_cosine_rejected() {
+        let path = temp_file("zero-norm-cosine");
+        let mut db = Database::create(&path, 3).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        let result = db.search(
+            &[0.0, 0.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                ..Default::default()
+            },
+        );
+        assert!(result.is_err(), "zero-norm cosine search should fail");
+        let err_msg = result.unwrap_err().to_string();
+        assert!(
+            err_msg.contains("zero norm"),
+            "error should mention zero norm: {err_msg}"
+        );
+        cleanup(&path);
+    }
+
+    #[test]
+    fn search_zero_norm_query_dotproduct_rejected() {
+        let path = temp_file("zero-norm-dot");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::DotProduct).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        let result = db.search(
+            &[0.0, 0.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                ..Default::default()
+            },
+        );
+        assert!(result.is_err(), "zero-norm dotproduct search should fail");
+        cleanup(&path);
+    }
+
+    #[test]
+    fn search_zero_norm_query_euclidean_allowed() {
+        let path = temp_file("zero-norm-euclidean");
+        let mut db =
+            Database::create_with_metric(&path, 3, DistanceMetric::Euclidean).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        // Euclidean distance from the origin is well-defined; should succeed.
+        let result = db.search(
+            &[0.0, 0.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                ..Default::default()
+            },
+        );
+        assert!(
+            result.is_ok(),
+            "zero-norm euclidean search should succeed: {:?}",
+            result.err()
+        );
+        cleanup(&path);
+    }
+
+    // ---------------------------------------------------------------
+    // Bug #15: dimension mismatch in search query should be rejected
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn search_undersized_query_rejected() {
+        let path = temp_file("dim-under");
+        let mut db = Database::create(&path, 4).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        // Query dim=2 on a dim=4 database without truncate_dim.
+        let result = db.search(
+            &[1.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                ..Default::default()
+            },
+        );
+        assert!(result.is_err(), "undersized query should fail");
+        match result.unwrap_err() {
+            VectLiteError::DimensionMismatch { expected, found } => {
+                assert_eq!(expected, 4);
+                assert_eq!(found, 2);
+            }
+            other => panic!("expected DimensionMismatch, got: {other}"),
+        }
+        cleanup(&path);
+    }
+
+    #[test]
+    fn search_oversized_query_rejected() {
+        let path = temp_file("dim-over");
+        let mut db = Database::create(&path, 3).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        let result = db.search(
+            &[1.0, 0.0, 0.0, 0.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                ..Default::default()
+            },
+        );
+        assert!(result.is_err(), "oversized query should fail");
+        match result.unwrap_err() {
+            VectLiteError::DimensionMismatch { expected, found } => {
+                assert_eq!(expected, 3);
+                assert_eq!(found, 5);
+            }
+            other => panic!("expected DimensionMismatch, got: {other}"),
+        }
+        cleanup(&path);
+    }
+
+    #[test]
+    fn search_undersized_query_with_truncate_dim_allowed() {
+        let path = temp_file("dim-matryoshka");
+        let mut db = Database::create(&path, 4).expect("create");
+        db.insert("a", vec![1.0, 0.0, 0.0, 0.0], Metadata::new())
+            .expect("insert");
+
+        // With explicit truncate_dim, undersized queries are Matryoshka-truncated.
+        let result = db.search(
+            &[1.0, 0.0],
+            SearchOptions {
+                top_k: 5,
+                truncate_dim: Some(2),
+                ..Default::default()
+            },
+        );
+        assert!(
+            result.is_ok(),
+            "truncate_dim query should succeed: {:?}",
+            result.err()
+        );
+        cleanup(&path);
+    }
 }