@omendb/omendb 0.0.24 → 0.0.26

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,20 +4,48 @@ 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)
+   *
+   * When any item includes a `text` field, text search is automatically enabled.
+   * This allows immediate use of searchHybrid() without calling enableTextSearch().
+   *
+   * @param items - Array of {id, vector, metadata?, text?} or {id, vectors, metadata?}
+   * @returns Number of vectors inserted/updated
    */
-  set(items: Array<VectorItem>): Array<number>
+  set(items: Array<SetItem>): number
   /**
    * Search for k nearest neighbors.
    *
    * @param query - Query vector (number[] or Float32Array)
    * @param k - Number of results to return
-   * @param ef - Optional search width override
-   * @param filter - Optional metadata filter (e.g., {category: "foo"} or {price: {$gt: 10}})
-   * @param maxDistance - Optional max distance threshold (filter out distant results)
+   * @param options - Optional search options: {filter?, ef?, maxDistance?}
+   * @returns Array of {id, distance, score, metadata}
+   *
+   * @example
+   * ```javascript
+   * // Basic search
+   * db.search([1, 0, 0, 0], 10);
+   *
+   * // With options
+   * db.search([1, 0, 0, 0], 10, { filter: { category: "A" }, ef: 200 });
+   * db.search([1, 0, 0, 0], 10, { maxDistance: 0.5 });
+   * ```
+   */
+  search(query: Array<number> | Float32Array, k: number, options?: { filter?: Record<string, unknown>; ef?: number; maxDistance?: number } | undefined): 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}
    */
-  search(query: Array<number> | Float32Array, k: number, ef?: number | undefined | null, filter?: Record<string, unknown> | undefined, maxDistance?: number | undefined | null): Array<SearchResult>
+  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).
    *
@@ -30,9 +58,21 @@ export declare class VectorDatabase {
   /**
    * Delete vectors by ID.
    *
+   * Accepts either a single ID string or an array of IDs.
+   *
+   * @param ids - Single ID string or array of IDs to delete
    * @returns Number of vectors deleted
+   *
+   * @example
+   * ```javascript
+   * // Delete single
+   * db.delete("doc1");
+   *
+   * // Delete multiple
+   * db.delete(["doc1", "doc2", "doc3"]);
+   * ```
    */
-  delete(ids: Array<string>): number
+  delete(ids: string | Array<string>): number
   /**
    * Delete vectors matching a metadata filter.
    *
@@ -77,12 +117,34 @@ export declare class VectorDatabase {
    * ```
    */
   count(filter?: Record<string, unknown> | undefined): number
-  /** Update a vector's data and/or metadata. */
-  update(id: string, vector: Array<number> | Float32Array, metadata?: Record<string, unknown> | undefined): void
+  /**
+   * Update a vector's data, metadata, and/or text.
+   *
+   * @param id - Vector ID to update
+   * @param options - Update options: {vector?, metadata?, text?}
+   *
+   * @example
+   * ```javascript
+   * // Update vector only
+   * db.update("doc1", { vector: [1, 0, 0, 0] });
+   *
+   * // Update metadata only
+   * db.update("doc1", { metadata: { status: "active" } });
+   *
+   * // Update text (re-indexed for BM25 search)
+   * db.update("doc1", { text: "Updated content for search" });
+   *
+   * // Update multiple fields
+   * db.update("doc1", { vector: [...], metadata: {...}, text: "..." });
+   * ```
+   */
+  update(id: string, options: { vector?: number[] | Float32Array; metadata?: Record<string, unknown>; text?: string }): void
   /** Get number of vectors in database. */
   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. */
@@ -103,20 +165,11 @@ export declare class VectorDatabase {
   /** Delete a collection. */
   deleteCollection(name: string): void
   /**
-   * Enable text search for hybrid (vector + text) search.
+   * Check if text search is enabled.
    *
-   * Must be called before using setWithText() or hybridSearch().
+   * Text search is automatically enabled when using set() with text field.
    */
-  enableTextSearch(): void
-  /** Check if text search is enabled. */
   get hasTextSearch(): boolean
-  /**
-   * Set vectors with associated text for hybrid search.
-   *
-   * @param items - Array of {id, vector, text, metadata?}
-   * @returns Array of internal indices
-   */
-  setWithText(items: Array<VectorItemWithText>): Array<number>
   /**
    * Search using text only (BM25 scoring).
    *
@@ -124,7 +177,7 @@ export declare class VectorDatabase {
    * @param k - Number of results
    * @returns Array of {id, score, metadata}
    */
-  textSearch(query: string, k: number): Array<TextSearchResult>
+  searchText(query: string, k: number): Array<TextSearchResult>
   /**
    * Hybrid search combining vector similarity and text relevance.
    *
@@ -133,13 +186,24 @@ export declare class VectorDatabase {
    * @param queryVector - Query embedding
    * @param queryText - Text query for BM25
    * @param k - Number of results
-   * @param filter - Optional metadata filter
-   * @param alpha - Weight for vector vs text (0.0=text only, 1.0=vector only, default=0.5)
-   * @param rrfK - RRF constant (default=60, higher reduces rank influence)
-   * @param subscores - Return separate keyword_score and semantic_score (default: false)
-   * @returns Array of {id, score, metadata, keyword_score?, semantic_score?}
+   * @param options - Optional: {filter?, alpha?, rrfK?, subscores?}
+   * @returns Array of {id, score, metadata, keywordScore?, semanticScore?}
+   *
+   * @example
+   * ```javascript
+   * // Basic hybrid search
+   * db.searchHybrid([1, 0, 0, 0], "machine learning", 10);
+   *
+   * // With options
+   * db.searchHybrid([1, 0, 0, 0], "query", 10, {
+   *   filter: { type: "ml" },
+   *   alpha: 0.7,
+   *   rrfK: 60,
+   *   subscores: true
+   * });
+   * ```
    */
-  hybridSearch(queryVector: Array<number> | Float32Array, queryText: string, k: number, filter?: Record<string, unknown> | undefined, alpha?: number | undefined | null, rrfK?: number | undefined | null, subscores?: boolean | undefined | null): Array<HybridSearchResult>
+  searchHybrid(queryVector: Array<number> | Float32Array, queryText: string, k: number, options?: { filter?: Record<string, unknown>; alpha?: number; rrfK?: number; subscores?: boolean } | undefined): Array<HybridSearchResult>
   /**
    * Flush pending changes to disk.
    *
@@ -207,6 +271,31 @@ export declare class VectorDatabase {
    * @returns true if ID exists and is not deleted
    */
   exists(id: string): boolean
+  /**
+   * Alias for exists() - check if an ID exists in the database.
+   *
+   * @param id - Vector ID to check
+   * @returns true if ID exists and is not deleted
+   */
+  has(id: string): boolean
+  /**
+   * Search for the single nearest neighbor.
+   *
+   * Convenience method that returns the top result or null if no matches.
+   *
+   * @param query - Query vector (number[] or Float32Array)
+   * @param options - Optional search options: {filter?, ef?, maxDistance?}
+   * @returns Single result or null
+   *
+   * @example
+   * ```javascript
+   * const nearest = db.searchOne([1, 0, 0, 0]);
+   * if (nearest) {
+   *   console.log(`Found: ${nearest.id} at distance ${nearest.distance}`);
+   * }
+   * ```
+   */
+  searchOne(query: Array<number> | Float32Array, options?: { filter?: Record<string, unknown>; ef?: number; maxDistance?: number } | undefined): SearchResult | null
   /**
    * Get multiple vectors by ID.
    *
@@ -234,6 +323,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,15 +408,37 @@ 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 {
   id: string
   distance: number
+  /** Normalized similarity score (0-1, higher = more similar) */
+  score: number
   /** Metadata as JSON (using serde-json feature) */
   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 text for hybrid search (auto-enables text search, stored in metadata.text) */
+  text?: 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,62 @@ 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)
+	 *
+	 * When any item includes a `text` field, text search is automatically enabled.
+	 *
+	 * @param {Array<{id: string, vector?: Float32Array|number[], vectors?: Float32Array[]|number[][], metadata?: object, text?: string}>} items
+	 * @returns {number} Number of vectors inserted/updated
+	 */
 	set(items) {
-		return this._native.set(items.map(convertVectorItem));
+		if (!Array.isArray(items)) {
+			throw new Error("set() requires an array of items");
+		}
+		if (items.length === 0) {
+			return 0;
+		}
+		// 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: {filter?, ef?, maxDistance?}
+	 * @returns {Array<{id: string, distance: number, score: 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 - pass options object directly to native
+			return this._native.search(query, k, options);
+		}
 	}
 
-	search(query, k, ef, filter, maxDistance) {
-		return this._native.search(query, k, ef, filter, maxDistance);
+	/**
+	 * Search for the single nearest neighbor.
+	 *
+	 * @param {number[]|Float32Array} query - Query vector
+	 * @param {object} [options] - Search options: {filter?, ef?, maxDistance?}
+	 * @returns {{id: string, distance: number, score: number, metadata: object}|null}
+	 */
+	searchOne(query, options) {
+		return this._native.searchOne(query, options);
 	}
 
 	searchBatch(queries, k, ef) {
@@ -153,8 +232,14 @@ class VectorDatabase {
 		return this._native.count(filter);
 	}
 
-	update(id, vector, metadata) {
-		return this._native.update(id, vector, metadata);
+	/**
+	 * Update a vector's data, metadata, and/or text.
+	 *
+	 * @param {string} id - Vector ID to update
+	 * @param {object} options - Update options: {vector?, metadata?, text?}
+	 */
+	update(id, options) {
+		return this._native.update(id, options);
 	}
 
 	get length() {
@@ -165,6 +250,10 @@ class VectorDatabase {
 		return this._native.dimensions;
 	}
 
+	get isMultiVector() {
+		return this._native.isMultiVector;
+	}
+
 	isEmpty() {
 		return this._native.isEmpty();
 	}
@@ -193,32 +282,32 @@ class VectorDatabase {
 		return this._native.deleteCollection(name);
 	}
 
-	enableTextSearch() {
-		return this._native.enableTextSearch();
-	}
-
 	get hasTextSearch() {
 		return this._native.hasTextSearch;
 	}
 
-	setWithText(items) {
-		return this._native.setWithText(items.map(convertVectorItem));
+	/**
+	 * Search using text only (BM25 scoring).
+	 *
+	 * @param {string} query - Text query
+	 * @param {number} k - Number of results
+	 * @returns {Array<{id: string, score: number, metadata: object}>}
+	 */
+	searchText(query, k) {
+		return this._native.searchText(query, k);
 	}
 
-	textSearch(query, k) {
-		return this._native.textSearch(query, k);
-	}
-
-	hybridSearch(queryVector, queryText, k, filter, alpha, rrfK, subscores) {
-		return this._native.hybridSearch(
-			queryVector,
-			queryText,
-			k,
-			filter,
-			alpha,
-			rrfK,
-			subscores,
-		);
+	/**
+	 * Hybrid search combining vector similarity and text relevance.
+	 *
+	 * @param {number[]|Float32Array} queryVector - Query embedding
+	 * @param {string} queryText - Text query for BM25
+	 * @param {number} k - Number of results
+	 * @param {object} [options] - Options: {filter?, alpha?, rrfK?, subscores?}
+	 * @returns {Array<{id: string, score: number, metadata: object, keywordScore?: number, semanticScore?: number}>}
+	 */
+	searchHybrid(queryVector, queryText, k, options) {
+		return this._native.searchHybrid(queryVector, queryText, k, options);
 	}
 
 	flush() {
@@ -249,9 +338,23 @@ class VectorDatabase {
 		return this._native.exists(id);
 	}
 
+	/**
+	 * Alias for exists() - check if an ID exists in the database.
+	 *
+	 * @param {string} id - Vector ID to check
+	 * @returns {boolean}
+	 */
+	has(id) {
+		return this._native.has(id);
+	}
+
 	getBatch(ids) {
 		return this._native.getBatch(ids);
 	}
+
+	compact() {
+		return this._native.compact();
+	}
 }
 
 function open(path, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "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.26",
+    "@omendb/omendb-darwin-arm64": "0.0.26",
+    "@omendb/omendb-linux-x64-gnu": "0.0.26",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.26",
+    "@omendb/omendb-win32-x64-msvc": "0.0.26"
   }
 }