@omendb/omendb 0.0.27 → 0.0.28

package/index.d.ts

@@ -166,8 +166,14 @@ export declare class VectorDatabase {
    * @returns Number of nodes reordered
    */
   optimize(): number
-  /** Merge another database into this one. */
-  mergeFrom(other: VectorDatabase): number
+  /**
+   * Merge another database into this one.
+   *
+   * @param other - Source database to merge from
+   * @param keyPrefix - Optional prefix for all source IDs (e.g., "subdir/")
+   * @returns Number of vectors merged
+   */
+  mergeFrom(other: VectorDatabase, keyPrefix?: string | undefined | null): number
   /**
    * List all vector IDs (without loading vector data).
    *
@@ -282,6 +288,73 @@ export declare class VectorDatabase {
    * keeping the Node.js event loop free.
    */
   searchBatch(queries: Array<Array<number> | Float32Array>, k: number, ef?: number | undefined | null): Promise<Array<Array<SearchResult>>>
+  /**
+   * Enable sparse vector indexing for SPLADE-style retrieval.
+   *
+   * Called automatically by setSparse() and setHybridSparse().
+   * Call explicitly before sparseSearch() on an empty index.
+   */
+  enableSparse(): void
+  /** Check if sparse indexing is enabled. */
+  get hasSparse(): boolean
+  /**
+   * Insert or update a sparse vector.
+   *
+   * @param id - Unique identifier
+   * @param sparse - Sparse vector as {indices: number[], values: number[]} or {dim: weight}
+   * @param metadata - Optional metadata
+   *
+   * @example
+   * ```javascript
+   * db.setSparse("doc1", {indices: [10, 42], values: [0.5, 1.2]}, {title: "Hello"});
+   * db.setSparse("doc2", {"10": 0.5, "42": 1.2}, {title: "World"});
+   * ```
+   */
+  setSparse(id: string, sparse: { indices: number[]; values: number[] } | Record<string, number>, metadata?: Record<string, unknown> | undefined): void
+  /**
+   * Insert or update both dense and sparse vectors together.
+   *
+   * @param id - Unique identifier
+   * @param vector - Dense vector
+   * @param sparse - Sparse vector
+   * @param metadata - Optional metadata
+   */
+  setHybridSparse(id: string, vector: Array<number> | Float32Array, sparse: { indices: number[]; values: number[] } | Record<string, number>, metadata?: Record<string, unknown> | undefined): void
+  /**
+   * Search sparse vectors by dot product similarity.
+   *
+   * @param query - Sparse query vector
+   * @param k - Number of results
+   * @param options - Optional: {filter?}
+   * @returns Array of {id, score, metadata} sorted by score descending
+   *
+   * @example
+   * ```javascript
+   * const results = db.sparseSearch({indices: [10, 42], values: [1.0, 0.5]}, 5);
+   * const results = db.sparseSearch({"10": 1.0, "42": 0.5}, 5);
+   * ```
+   */
+  sparseSearch(query: { indices: number[]; values: number[] } | Record<string, number>, k: number, options?: { filter?: Record<string, unknown> } | undefined): Array<SparseSearchResult>
+  /**
+   * Hybrid dense + sparse search with Reciprocal Rank Fusion (RRF).
+   *
+   * @param queryVector - Dense query vector
+   * @param sparseQuery - Sparse query vector
+   * @param k - Number of results
+   * @param options - Optional: {alpha?, filter?}
+   * @returns Array of {id, score, metadata}
+   *
+   * @example
+   * ```javascript
+   * const results = db.hybridSparseSearch(
+   *   [1, 0, 0],
+   *   {indices: [10, 42], values: [1.0, 0.5]},
+   *   10,
+   *   { alpha: 0.5 }
+   * );
+   * ```
+   */
+  hybridSparseSearch(queryVector: Array<number> | Float32Array, sparseQuery: { indices: number[]; values: number[] } | Record<string, number>, k: number, options?: { alpha?: number; filter?: Record<string, unknown> } | undefined): Array<SparseSearchResult>
 }
 
 export interface GetResult {
@@ -366,6 +439,10 @@ export interface OpenOptions {
    * - false/null: Disabled (default, single-vector mode)
    */
   multiVector?: boolean | { repetitions?: number; partitionBits?: number; seed?: number; dProj?: number | null } | null | undefined
+  /** SQ8 refiner: rescore with full precision (default: true when quantized) */
+  rescore?: boolean
+  /** Candidate multiplier for rescoring (default: 3.0) */
+  oversample?: number
 }
 
 export interface SearchResult {
@@ -391,6 +468,14 @@ export interface SetItem {
   document?: string
 }
 
+/** Sparse search result returned from sparseSearch / hybridSparseSearch. */
+export interface SparseSearchResult {
+  id: string
+  /** Dot product score (higher = more similar) */
+  score: number
+  metadata: Record<string, unknown>
+}
+
 export interface StatsResult {
   dimensions: number
   count: number

package/index.js

@@ -337,6 +337,30 @@ class VectorDatabase {
 	compact() {
 		return this._native.compact();
 	}
+
+	enableSparse() {
+		return this._native.enableSparse();
+	}
+
+	get hasSparse() {
+		return this._native.hasSparse;
+	}
+
+	setSparse(id, sparse, metadata) {
+		return this._native.setSparse(id, sparse, metadata);
+	}
+
+	setHybridSparse(id, vector, sparse, metadata) {
+		return this._native.setHybridSparse(id, vector, sparse, metadata);
+	}
+
+	sparseSearch(query, k, options) {
+		return this._native.sparseSearch(query, k, options);
+	}
+
+	hybridSparseSearch(queryVector, sparseQuery, k, options) {
+		return this._native.hybridSparseSearch(queryVector, sparseQuery, k, options);
+	}
 }
 
 function open(path, options, embeddingFn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "Fast embedded vector database with HNSW + ACORN-1 filtered search",
   "main": "index.js",
   "types": "index.d.ts",
@@ -50,10 +50,10 @@
     "omendb.node"
   ],
   "optionalDependencies": {
-    "@omendb/omendb-darwin-x64": "0.0.27",
-    "@omendb/omendb-darwin-arm64": "0.0.27",
-    "@omendb/omendb-linux-x64-gnu": "0.0.27",
-    "@omendb/omendb-linux-arm64-gnu": "0.0.27",
-    "@omendb/omendb-win32-x64-msvc": "0.0.27"
+    "@omendb/omendb-darwin-x64": "0.0.28",
+    "@omendb/omendb-darwin-arm64": "0.0.28",
+    "@omendb/omendb-linux-x64-gnu": "0.0.28",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.28",
+    "@omendb/omendb-win32-x64-msvc": "0.0.28"
   }
 }