@omendb/omendb 0.0.24 → 0.0.25

package/README.md

@@ -31,11 +31,11 @@ db.set([
 ]);
 
 // Search
-const results = db.search(new Float32Array(384).fill(0.15), { k: 5 });
+const results = db.search(new Float32Array(384).fill(0.15), 5);
 // [{ id: 'doc1', distance: 0.05, metadata: { title: 'Hello' } }, ...]
 
 // Batch search (async, parallel)
-const batchResults = await db.searchBatch(queries, { k: 10 });
+const batchResults = await db.searchBatch(queries, 10);
 
 // Close when done (releases file locks)
 db.close();
@@ -139,13 +139,13 @@ const deleted = db.deleteByFilter({
 
 ### Search
 
-#### `db.search(query, options)`
+#### `db.search(query, k, options?)`
 
 Search for k nearest neighbors (sync).
 
 ```typescript
-const results = db.search(queryVector, {
-  k: 10, // Number of results
+const results = db.search(queryVector, 10); // Basic
+const results = db.search(queryVector, 10, {
   ef: 200, // Search quality (higher = better recall)
   filter: { category: "news" }, // Metadata filter
   maxDistance: 0.5, // Distance threshold
@@ -153,12 +153,12 @@ const results = db.search(queryVector, {
 // [{ id, distance, metadata }, ...]
 ```
 
-#### `db.searchBatch(queries, options)`
+#### `db.searchBatch(queries, k, ef?)`
 
 Batch search with parallel execution (async).
 
 ```typescript
-const results = await db.searchBatch(queries, { k: 10, ef: 100 });
+const results = await db.searchBatch(queries, 10, 100);
 // [[{ id, distance, metadata }, ...], ...]
 ```
 
@@ -224,7 +224,7 @@ Get or create a named collection.
 ```typescript
 const users = db.collection("users");
 users.set([...]);
-users.search(query, { k: 5 });
+users.search(query, 5);
 ```
 
 #### `db.collections()`
@@ -373,11 +373,11 @@ const merged = db.mergeFrom(otherDb);
 
 **10K vectors, 128D, M=16, ef=100. Measured 2026-01-20 (Apple M3 Max):**
 
-| Metric     | Value     |
-| ---------- | --------- |
-| Search QPS | 11,542    |
+| Metric     | Value        |
+| ---------- | ------------ |
+| Search QPS | 11,542       |
 | Build      | 30,826 vec/s |
-| Recall@10  | 89.7%     |
+| Recall@10  | 89.7%        |
 
 ## License
 

package/index.d.ts

@@ -4,9 +4,14 @@ export declare class VectorDatabase {
   /**
    * Insert or update vectors.
    *
-   * Accepts an array of items with id, vector, and optional metadata.
+   * Works for both single-vector and multi-vector stores:
+   * - Single-vector: items have `vector` field
+   * - Multi-vector: items have `vectors` field (array of vectors)
+   *
+   * @param items - Array of {id, vector, metadata?} or {id, vectors, metadata?}
+   * @returns Array of internal indices
    */
-  set(items: Array<VectorItem>): Array<number>
+  set(items: Array<SetItem>): Array<number>
   /**
    * Search for k nearest neighbors.
    *
@@ -18,6 +23,18 @@ export declare class VectorDatabase {
    * @returns Array of {id, distance, metadata}
    */
   search(query: Array<number> | Float32Array, k: number, ef?: number | undefined | null, filter?: Record<string, unknown> | undefined, maxDistance?: number | undefined | null): Array<SearchResult>
+  /**
+   * Search multi-vector store with query tokens.
+   *
+   * Internal method used by unified search() for multi-vector stores.
+   *
+   * @param query - Query tokens (number[][] or Float32Array[])
+   * @param k - Number of results to return
+   * @param rerank - Enable MaxSim reranking for better quality (default: true)
+   * @param rerankFactor - Fetch k*rerankFactor candidates before reranking (default: 32)
+   * @returns Array of {id, distance, metadata}
+   */
+  searchMulti(query: Array<Array<number>> | Array<Float32Array>, k: number, rerank?: boolean | undefined | null, rerankFactor?: number | undefined | null): Array<SearchResult>
   /**
    * Batch search with parallel execution (async).
    *
@@ -83,6 +100,8 @@ export declare class VectorDatabase {
   get length(): number
   /** Get vector dimensions of this database. */
   get dimensions(): number
+  /** Check if this is a multi-vector store. */
+  get isMultiVector(): boolean
   /** Check if database is empty. */
   isEmpty(): boolean
   /** Get database statistics. */
@@ -234,6 +253,14 @@ export interface HybridSearchResult {
   semanticScore?: number
 }
 
+export interface MultiVectorItem {
+  id: string
+  /** Multi-vector data as array of Float32Arrays */
+  vectors: Float32Array[]
+  /** Optional metadata */
+  metadata?: Record<string, unknown> | undefined
+}
+
 /**
  * Open or create a vector database.
  *
@@ -311,6 +338,14 @@ export interface OpenOptions {
   oversample?: number
   /** Distance metric: "l2"/"euclidean" (default), "cosine", "dot"/"ip" */
   metric?: string
+  /**
+   * Enable multi-vector mode for ColBERT-style retrieval
+   * - true: Enable with default config (repetitions=8, partition_bits=4, dProj=16)
+   * - { repetitions?, partitionBits?, seed?, dProj? }: Custom config
+   * - dProj: Dimension projection (16 = 8x smaller FDE, null = full token dim)
+   * - false/null: Disabled (default, single-vector mode)
+   */
+  multiVector?: boolean | { repetitions?: number; partitionBits?: number; seed?: number; dProj?: number | null } | null | undefined
 }
 
 export interface SearchResult {
@@ -320,6 +355,18 @@ export interface SearchResult {
   metadata: Record<string, unknown>
 }
 
+export interface SetItem {
+  id: string
+  /** Single vector data (for regular stores) */
+  vector?: Float32Array
+  /** Multi-vector data (for multi-vector stores) */
+  vectors?: Float32Array[] | undefined
+  /** Optional metadata */
+  metadata?: Record<string, unknown> | undefined
+  /** Optional document text (stored in metadata.document) */
+  document?: string
+}
+
 export interface StatsResult {
   dimensions: number
   count: number

package/index.js

@@ -111,12 +111,41 @@ function toFloat32Array(arr) {
 
 // Convert VectorItem to use Float32Array
 function convertVectorItem(item) {
+	if (item.vector === undefined || item.vector === null) {
+		if (Array.isArray(item.vectors)) {
+			throw new Error(
+				`Item '${item.id}' has 'vectors' field but store is single-vector. Use multiVector: true when opening the database.`,
+			);
+		}
+		throw new Error(`Item '${item.id}' missing required 'vector' field`);
+	}
 	return {
 		...item,
 		vector: toFloat32Array(item.vector),
 	};
 }
 
+// Convert MultiVectorItem to use Float32Arrays
+function convertMultiVectorItem(item) {
+	if (!Array.isArray(item.vectors)) {
+		if (item.vector !== undefined) {
+			throw new Error(
+				`Item '${item.id}' has 'vector' field but store is multi-vector. Use 'vectors' field (array of vectors) instead.`,
+			);
+		}
+		throw new Error(`Item '${item.id}' missing required 'vectors' field`);
+	}
+	return {
+		...item,
+		vectors: item.vectors.map(toFloat32Array),
+	};
+}
+
+// Check if items contain multi-vector data (vectors field must be an array)
+function isMultiVectorItem(item) {
+	return Array.isArray(item.vectors);
+}
+
 // Wrap VectorDatabase to handle array conversion
 const NativeVectorDatabase = nativeBinding.VectorDatabase;
 
@@ -125,12 +154,69 @@ class VectorDatabase {
 		this._native = nativeDb;
 	}
 
+	/**
+	 * Insert or update vectors.
+	 *
+	 * Works for both single-vector and multi-vector stores:
+	 * - Single-vector: items have `vector` field
+	 * - Multi-vector: items have `vectors` field (array of vectors)
+	 *
+	 * @param {Array<{id: string, vector?: Float32Array|number[], vectors?: Float32Array[]|number[][], metadata?: object}>} items
+	 * @returns {number[]} Array of internal indices
+	 */
 	set(items) {
-		return this._native.set(items.map(convertVectorItem));
-	}
-
-	search(query, k, ef, filter, maxDistance) {
-		return this._native.search(query, k, ef, filter, maxDistance);
+		if (!Array.isArray(items)) {
+			throw new Error("set() requires an array of items");
+		}
+		if (items.length === 0) {
+			return [];
+		}
+		// Unified set() handles both single and multi-vector via native set()
+		return this._native.set(items.map(this._native.isMultiVector ? convertMultiVectorItem : convertVectorItem));
+	}
+
+	/**
+	 * Search for k nearest neighbors.
+	 *
+	 * Works for both single-vector and multi-vector stores:
+	 * - Single-vector: query is number[] or Float32Array
+	 * - Multi-vector: query is number[][] or Float32Array[]
+	 *
+	 * @param {number[]|Float32Array|number[][]|Float32Array[]} query - Query vector(s)
+	 * @param {number} k - Number of results to return
+	 * @param {object} [options] - Search options
+	 * @param {number} [options.ef] - Search width override (single-vector only)
+	 * @param {object} [options.filter] - Metadata filter (single-vector only)
+	 * @param {number} [options.maxDistance] - Max distance threshold (single-vector only)
+	 * @param {boolean} [options.rerank] - Enable MaxSim reranking (multi-vector, default: true)
+	 * @param {number} [options.rerankFactor] - Rerank candidate multiplier (multi-vector, default: 4)
+	 * @returns {Array<{id: string, distance: number, metadata: object}>}
+	 */
+	search(query, k, options) {
+		if (this._native.isMultiVector) {
+			// Multi-vector store
+			const rerank = options?.rerank;
+			const rerankFactor = options?.rerankFactor;
+			return this._native.searchMulti(query, k, rerank, rerankFactor);
+		} else {
+			// Single-vector store - support both old positional args and new options object
+			if (typeof options === "object" && options !== null && !Array.isArray(options)) {
+				// New options object style
+				return this._native.search(
+					query,
+					k,
+					options.ef,
+					options.filter,
+					options.maxDistance,
+				);
+			} else {
+				// Legacy positional args: search(query, k, ef, filter, maxDistance)
+				const ef = options; // 3rd arg was ef in old API
+				const filter = arguments[3];
+				const maxDistance = arguments[4];
+				return this._native.search(query, k, ef, filter, maxDistance);
+			}
+		}
 	}
 
 	searchBatch(queries, k, ef) {
@@ -165,6 +251,10 @@ class VectorDatabase {
 		return this._native.dimensions;
 	}
 
+	get isMultiVector() {
+		return this._native.isMultiVector;
+	}
+
 	isEmpty() {
 		return this._native.isEmpty();
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "Fast embedded vector database with HNSW + ACORN-1 filtered search",
   "main": "index.js",
   "types": "index.d.ts",
@@ -41,7 +41,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.5.0",
+    "@napi-rs/cli": "^3.5.1",
     "vitest": "^2.1.0"
   },
   "files": [
@@ -50,10 +50,10 @@
     "omendb.node"
   ],
   "optionalDependencies": {
-    "@omendb/omendb-darwin-x64": "0.0.24",
-    "@omendb/omendb-darwin-arm64": "0.0.24",
-    "@omendb/omendb-linux-x64-gnu": "0.0.24",
-    "@omendb/omendb-linux-arm64-gnu": "0.0.24",
-    "@omendb/omendb-win32-x64-msvc": "0.0.24"
+    "@omendb/omendb-darwin-x64": "0.0.25",
+    "@omendb/omendb-darwin-arm64": "0.0.25",
+    "@omendb/omendb-linux-x64-gnu": "0.0.25",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.25",
+    "@omendb/omendb-win32-x64-msvc": "0.0.25"
   }
 }