vectlite 0.1.11 → 0.1.12

package/README.md

@@ -46,6 +46,7 @@ db.close()
 - **Dense vectors** -- cosine similarity with automatic HNSW indexing for large collections
 - **Sparse vectors** -- BM25-scored inverted index for keyword retrieval
 - **Hybrid search** -- dense + sparse fusion with linear or RRF strategies
+- **Vector quantization** -- scalar (int8, 4x), binary (32x), and product quantization (PQ) with 2-stage rescoring
 - **Rich metadata** -- string, number, boolean, null, array, and nested object values
 - **Crash-safe WAL** -- writes land in a write-ahead log first, then checkpoint with `compact()`
 - **Transactions** -- atomic batched writes with `db.transaction()`
@@ -183,6 +184,33 @@ console.log(outcome.stats.used_ann)     // true
 console.log(outcome.results[0].explain) // Detailed scoring breakdown
 ```
 
+### Vector Quantization
+
+Reduce memory usage and accelerate search with quantized vectors. All methods use a 2-stage pipeline: fast quantized candidate selection followed by exact float32 rescoring.
+
+```js
+// Scalar quantization (int8) -- 4x memory reduction, minimal recall loss
+db.enableQuantization('scalar')
+
+// Binary quantization -- 32x memory reduction, best for normalized embeddings
+db.enableQuantization('binary', JSON.stringify({ rescoreMultiplier: 10 }))
+
+// Product quantization -- configurable compression for very large datasets
+db.enableQuantization('product', JSON.stringify({ numSubVectors: 16, numCentroids: 256 }))
+
+// Search works exactly the same -- quantization accelerates it transparently
+const results = db.search(queryEmbedding, { k: 10 })
+
+// Check quantization status
+console.log(db.isQuantized)         // true
+console.log(db.quantizationMethod)  // "scalar", "binary", or "product"
+
+// Disable quantization
+db.disableQuantization()
+```
+
+Quantization parameters persist across reopens in a `.vdb.quant` sidecar file. The quantized index auto-rebuilds on inserts and upserts.
+
 ## Database Methods Reference
 
 ### Write Methods
@@ -212,6 +240,15 @@ console.log(outcome.results[0].explain) // Detailed scoring breakdown
 | `db.path` | Database file path (property) |
 | `db.readOnly` | Whether the database is read-only (property) |
 
+### Quantization Methods
+
+| Method | Description |
+|---|---|
+| `db.enableQuantization(method, optionsJson)` | Enable quantization (`'scalar'`, `'binary'`, or `'product'`) |
+| `db.disableQuantization()` | Disable quantization and remove persisted parameters |
+| `db.isQuantized` | Whether quantization is enabled (property) |
+| `db.quantizationMethod` | Active method name or `null` (property) |
+
 ### Maintenance Methods
 
 | Method | Description |

package/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectlite-node"
-version = "0.1.11"
+version = "0.1.12"
 edition = "2024"
 license = "MIT"
 description = "Node.js bindings for vectlite."

package/native/src/lib.rs

@@ -6,6 +6,10 @@ use napi::Error as NapiError;
 use napi::bindgen_prelude::*;
 use napi_derive::napi;
 use serde_json::{Map, Number, Value, json};
+use vectlite::quantization::{
+    BinaryQuantizationConfig, ProductQuantizationConfig, QuantizationConfig,
+    ScalarQuantizationConfig,
+};
 use vectlite::{
     Database as CoreDatabase, FusionStrategy, HybridSearchOptions, Metadata, MetadataFilter,
     MetadataValue, NamedVectors, Record, SearchOutcome, SearchResult, SparseVector,
@@ -348,6 +352,58 @@ impl NativeDatabase {
         database.compact().map_err(to_napi_error)
     }
 
+    // -------------------------------------------------------------------
+    // Quantization
+    // -------------------------------------------------------------------
+
+    /// Enable quantization on the database.
+    /// `method`: "scalar", "binary", or "product"
+    /// `options_json`: JSON with optional keys: rescore_multiplier, num_sub_vectors, num_centroids, training_iterations
+    #[napi(js_name = "enableQuantization")]
+    pub fn enable_quantization(
+        &self,
+        method: Option<String>,
+        options_json: Option<String>,
+    ) -> Result<()> {
+        let method = method.as_deref().unwrap_or("scalar");
+        let (rescore_multiplier, num_sub_vectors, num_centroids, training_iterations) =
+            parse_quantization_options(options_json.as_deref())?;
+        let config = build_quantization_config(
+            method,
+            rescore_multiplier,
+            num_sub_vectors,
+            num_centroids,
+            training_iterations,
+        )?;
+        let mut database = self.write_open()?;
+        database.enable_quantization(config).map_err(to_napi_error)
+    }
+
+    /// Disable quantization and remove persisted parameters.
+    #[napi(js_name = "disableQuantization")]
+    pub fn disable_quantization(&self) -> Result<()> {
+        let mut database = self.write_open()?;
+        database.disable_quantization().map_err(to_napi_error)
+    }
+
+    /// Returns true if quantization is enabled.
+    #[napi(getter, js_name = "isQuantized")]
+    pub fn is_quantized(&self) -> Result<bool> {
+        let database = self.read()?;
+        Ok(database.is_quantized())
+    }
+
+    /// Returns the quantization method name if enabled, else null.
+    #[napi(getter, js_name = "quantizationMethod")]
+    pub fn quantization_method(&self) -> Result<Option<String>> {
+        let database = self.read()?;
+        Ok(database.quantization_config().map(|config| match config {
+            QuantizationConfig::Scalar(_) => "scalar".to_owned(),
+            QuantizationConfig::Binary(_) => "binary".to_owned(),
+            QuantizationConfig::Product(_) => "product".to_owned(),
+        }))
+    }
+
     #[napi]
     pub fn snapshot(&self, dest: String) -> Result<()> {
         let database = self.read()?;
@@ -1315,3 +1371,70 @@ fn to_napi_error(error: vectlite::VectLiteError) -> NapiError {
 fn closed_database_error() -> vectlite::VectLiteError {
     vectlite::VectLiteError::InvalidFormat("database is closed".to_owned())
 }
+
+fn parse_quantization_options(
+    options_json: Option<&str>,
+) -> Result<(Option<usize>, Option<usize>, Option<usize>, Option<usize>)> {
+    let Some(json_str) = options_json else {
+        return Ok((None, None, None, None));
+    };
+    let value: Value = serde_json::from_str(json_str)
+        .map_err(|e| err(format!("invalid quantization options JSON: {e}")))?;
+    let obj = value
+        .as_object()
+        .ok_or_else(|| err("quantization options must be a JSON object"))?;
+
+    let rescore_multiplier = obj
+        .get("rescoreMultiplier")
+        .or_else(|| obj.get("rescore_multiplier"))
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+    let num_sub_vectors = obj
+        .get("numSubVectors")
+        .or_else(|| obj.get("num_sub_vectors"))
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+    let num_centroids = obj
+        .get("numCentroids")
+        .or_else(|| obj.get("num_centroids"))
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+    let training_iterations = obj
+        .get("trainingIterations")
+        .or_else(|| obj.get("training_iterations"))
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+
+    Ok((
+        rescore_multiplier,
+        num_sub_vectors,
+        num_centroids,
+        training_iterations,
+    ))
+}
+
+fn build_quantization_config(
+    method: &str,
+    rescore_multiplier: Option<usize>,
+    num_sub_vectors: Option<usize>,
+    num_centroids: Option<usize>,
+    training_iterations: Option<usize>,
+) -> Result<QuantizationConfig> {
+    match method {
+        "scalar" | "int8" => Ok(QuantizationConfig::Scalar(ScalarQuantizationConfig {
+            rescore_multiplier: rescore_multiplier.unwrap_or(5),
+        })),
+        "binary" => Ok(QuantizationConfig::Binary(BinaryQuantizationConfig {
+            rescore_multiplier: rescore_multiplier.unwrap_or(10),
+        })),
+        "product" | "pq" => Ok(QuantizationConfig::Product(ProductQuantizationConfig {
+            num_sub_vectors: num_sub_vectors.unwrap_or(16),
+            num_centroids: num_centroids.unwrap_or(256),
+            training_iterations: training_iterations.unwrap_or(20),
+            rescore_multiplier: rescore_multiplier.unwrap_or(10),
+        })),
+        other => Err(err(format!(
+            "unknown quantization method '{other}'. Expected: 'scalar', 'binary', or 'product'"
+        ))),
+    }
+}

package/native/vectlite-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectlite-core"
-version = "0.1.11"
+version = "0.1.12"
 edition = "2024"
 license = "MIT"
 description = "Core storage engine for vectlite."