@omendb/omendb 0.0.9 → 0.0.11

package/index.d.ts

@@ -1,103 +1,200 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 export declare class VectorDatabase {
-  /**
-   * Insert or update vectors.
-   *
-   * Accepts an array of items with id, vector, and optional metadata.
-   */
-  set(items: Array<VectorItem>): Array<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}})
-   * @returns Array of {id, distance, metadata}
-   */
-  search(query: Array<number> | Float32Array, k: number, ef?: number | undefined | null, filter?: Record<string, unknown> | undefined): Array<SearchResult>
-  /**
-   * Batch search with parallel execution (async).
-   *
-   * Runs searches in parallel using rayon, returns Promise.
-   */
-  searchBatch(queries: Array<Array<number> | Float32Array>, k: number, ef?: number | undefined | null): Promise<Array<Array<SearchResult>>>
-  /** Get a vector by ID. */
-  get(id: string): GetResult | null
-  /**
-   * Delete vectors by ID.
-   *
-   * @returns Number of vectors deleted
-   */
-  delete(ids: Array<string>): number
-  /** Update a vector's data and/or metadata. */
-  update(id: string, vector: Array<number> | Float32Array, metadata?: Record<string, unknown> | undefined): void
-  /** Save database to disk. */
-  save(): void
-  /** Get number of vectors in database. */
-  get count(): number
-  /** Get current ef_search value. */
-  get efSearch(): number | null
-  /** Set ef_search value. */
-  set efSearch(efSearch: number)
-  /** Get or create a named collection. */
-  collection(name: string): VectorDatabase
-  /** List all collections. */
-  collections(): Array<string>
-  /** Delete a collection. */
-  deleteCollection(name: string): void
-  /**
-   * Enable text search for hybrid (vector + text) search.
-   *
-   * Must be called before using setWithText() or hybridSearch().
-   */
-  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).
-   *
-   * @param query - Text query
-   * @param k - Number of results
-   * @returns Array of {id, score, metadata}
-   */
-  textSearch(query: string, k: number): Array<TextSearchResult>
-  /**
-   * Hybrid search combining vector similarity and text relevance.
-   *
-   * Uses Reciprocal Rank Fusion (RRF) to combine HNSW and BM25 results.
-   *
-   * @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)
-   * @returns Array of {id, score, metadata}
-   */
-  hybridSearch(queryVector: Array<number> | Float32Array, queryText: string, k: number, filter?: Record<string, unknown> | undefined, alpha?: number | undefined | null, rrfK?: number | undefined | null): Array<TextSearchResult>
-  /**
-   * Flush pending changes to disk.
-   *
-   * For hybrid search, this commits text index changes.
-   */
-  flush(): void
-  /** Merge another database into this one. */
-  mergeFrom(other: VectorDatabase): number
+	/**
+	 * Insert or update vectors.
+	 *
+	 * Accepts an array of items with id, vector, and optional metadata.
+	 */
+	set(items: Array<VectorItem>): Array<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}})
+	 * @returns Array of {id, distance, metadata}
+	 */
+	search(
+		query: Array<number> | Float32Array,
+		k: number,
+		ef?: number | undefined | null,
+		filter?: Record<string, unknown> | undefined,
+	): Array<SearchResult>;
+	/**
+	 * Batch search with parallel execution (async).
+	 *
+	 * Runs searches in parallel using rayon, returns Promise.
+	 */
+	searchBatch(
+		queries: Array<Array<number> | Float32Array>,
+		k: number,
+		ef?: number | undefined | null,
+	): Promise<Array<Array<SearchResult>>>;
+	/** Get a vector by ID. */
+	get(id: string): GetResult | null;
+	/**
+	 * Delete vectors by ID.
+	 *
+	 * @returns Number of vectors deleted
+	 */
+	delete(ids: Array<string>): number;
+	/**
+	 * Delete vectors matching a metadata filter.
+	 *
+	 * Evaluates the filter against all vectors and deletes those that match.
+	 * Uses the same MongoDB-style filter syntax as search().
+	 *
+	 * @param filter - MongoDB-style metadata filter
+	 * @returns Number of vectors deleted
+	 *
+	 * @example
+	 * ```javascript
+	 * // Delete by equality
+	 * db.deleteWhere({ status: "archived" });
+	 *
+	 * // Delete with comparison
+	 * db.deleteWhere({ score: { $lt: 0.5 } });
+	 *
+	 * // Complex filter
+	 * db.deleteWhere({ $and: [{ type: "draft" }, { age: { $gt: 30 } }] });
+	 * ```
+	 */
+	deleteWhere(filter: Record<string, unknown>): number;
+	/**
+	 * Count vectors, optionally filtered by metadata.
+	 *
+	 * Without a filter, returns total count (same as db.length).
+	 * With a filter, returns count of vectors matching the filter.
+	 *
+	 * @param filter - Optional MongoDB-style metadata filter
+	 * @returns Number of vectors (matching filter if provided)
+	 *
+	 * @example
+	 * ```javascript
+	 * // Total count
+	 * const total = db.count();
+	 *
+	 * // Filtered count
+	 * const active = db.count({ status: "active" });
+	 *
+	 * // With comparison operators
+	 * const highScore = db.count({ score: { $gte: 0.8 } });
+	 * ```
+	 */
+	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;
+	/** Get number of vectors in database. */
+	get length(): number;
+	/** Get current ef_search value. */
+	get efSearch(): number;
+	/** Set ef_search value. */
+	set efSearch(efSearch: number);
+	/**
+	 * Get or create a named collection.
+	 *
+	 * Collection handles share state - changes made through one handle
+	 * are immediately visible through another (no flush required).
+	 */
+	collection(name: string): VectorDatabase;
+	/** List all collections. */
+	collections(): Array<string>;
+	/** Delete a collection. */
+	deleteCollection(name: string): void;
+	/**
+	 * Enable text search for hybrid (vector + text) search.
+	 *
+	 * Must be called before using setWithText() or hybridSearch().
+	 */
+	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).
+	 *
+	 * @param query - Text query
+	 * @param k - Number of results
+	 * @returns Array of {id, score, metadata}
+	 */
+	textSearch(query: string, k: number): Array<TextSearchResult>;
+	/**
+	 * Hybrid search combining vector similarity and text relevance.
+	 *
+	 * Uses Reciprocal Rank Fusion (RRF) to combine HNSW and BM25 results.
+	 *
+	 * @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)
+	 * @returns Array of {id, score, metadata}
+	 */
+	hybridSearch(
+		queryVector: Array<number> | Float32Array,
+		queryText: string,
+		k: number,
+		filter?: Record<string, unknown> | undefined,
+		alpha?: number | undefined | null,
+		rrfK?: number | undefined | null,
+	): Array<TextSearchResult>;
+	/**
+	 * Flush pending changes to disk.
+	 *
+	 * For hybrid search, this commits text index changes.
+	 */
+	flush(): void;
+	/** Merge another database into this one. */
+	mergeFrom(other: VectorDatabase): number;
+	/**
+	 * List all vector IDs (without loading vector data).
+	 *
+	 * Efficient way to get all IDs for iteration, export, or debugging.
+	 * @returns Array of all vector IDs in the database
+	 */
+	ids(): Array<string>;
+	/**
+	 * Get all items as array of {id, vector, metadata}.
+	 *
+	 * Returns all vectors with their IDs and metadata.
+	 * For large datasets, consider using ids() and get() in batches.
+	 */
+	items(): Array<GetResult>;
+	/**
+	 * Check if an ID exists in the database.
+	 *
+	 * @param id - Vector ID to check
+	 * @returns true if ID exists and is not deleted
+	 */
+	exists(id: string): boolean;
+	/**
+	 * Get multiple vectors by ID.
+	 *
+	 * Batch version of get(). More efficient than calling get() in a loop.
+	 *
+	 * @param ids - Array of vector IDs to retrieve
+	 * @returns Array of results in same order as input, null for missing IDs
+	 */
+	getMany(ids: Array<string>): Array<GetResult | undefined | null>;
 }
 
 export interface GetResult {
-  id: string
-  vector: Array<number>
-  metadata: Record<string, unknown>
+	id: string;
+	vector: Array<number>;
+	metadata: Record<string, unknown>;
 }
 
 /**
@@ -125,9 +222,20 @@ export interface GetResult {
  *   dimensions: 128,
  *   quantization: 4  // 4-bit quantization
  * });
+ *
+ * // Quantization with custom rescore settings
+ * const db = omendb.open("./mydb", {
+ *   dimensions: 128,
+ *   quantization: 4,
+ *   rescore: false,    // Disable rescore for max speed
+ *   oversample: 5.0    // Or increase oversample for better recall
+ * });
  * ```
  */
-export declare function open(path: string, options?: OpenOptions | undefined | null): VectorDatabase
+export declare function open(
+	path: string,
+	options?: OpenOptions | undefined | null,
+): VectorDatabase;
 
 /**
  * Configuration options for opening a vector database.
@@ -138,49 +246,64 @@ export declare function open(path: string, options?: OpenOptions | undefined | n
  * - efConstruction: 100 (build quality, higher = better graph, slower build)
  * - efSearch: 100 (search quality, higher = better recall, slower search)
  * - quantization: null (RaBitQ bit width: 2, 4, or 8 for compression)
+ * - rescore: true when quantization enabled (rerank candidates with exact distance)
+ * - oversample: 3.0 (fetch k*oversample candidates when rescoring)
+ * - metric: "l2" (distance metric: "l2", "euclidean", "cosine", "dot", "ip")
  */
 export interface OpenOptions {
-  /** Vector dimensions (default: 128, auto-detected on first insert) */
-  dimensions?: number
-  /** HNSW M parameter: neighbors per node (default: 16, range: 4-64) */
-  m?: number
-  /** HNSW ef_construction: build quality (default: 100, must be >= m) */
-  efConstruction?: number
-  /** HNSW ef_search: search quality/speed tradeoff (default: 100) */
-  efSearch?: number
-  /**
-   * RaBitQ quantization bits: 2, 4, or 8 (default: null = no quantization)
-   * Enables 4-16x memory compression with ~1-2% recall loss
-   */
-  quantization?: number
+	/** Vector dimensions (default: 128, auto-detected on first insert) */
+	dimensions?: number;
+	/** HNSW M parameter: neighbors per node (default: 16, range: 4-64) */
+	m?: number;
+	/** HNSW ef_construction: build quality (default: 100, must be >= m) */
+	efConstruction?: number;
+	/** HNSW ef_search: search quality/speed tradeoff (default: 100) */
+	efSearch?: number;
+	/**
+	 * RaBitQ quantization bits: 2, 4, or 8 (default: null = no quantization)
+	 * Enables 4-16x memory compression with ~1-2% recall loss
+	 */
+	quantization?: number;
+	/**
+	 * Rescore candidates with exact distance (default: true when quantization enabled)
+	 * Set to false for maximum speed at the cost of ~20% recall
+	 */
+	rescore?: boolean;
+	/**
+	 * Oversampling factor for rescoring (default: 3.0)
+	 * Fetches k*oversample candidates then reranks to return top k
+	 */
+	oversample?: number;
+	/** Distance metric: "l2"/"euclidean" (default), "cosine", "dot"/"ip" */
+	metric?: string;
 }
 
 export interface SearchResult {
-  id: string
-  distance: number
-  /** Metadata as JSON (using serde-json feature) */
-  metadata: Record<string, unknown>
+	id: string;
+	distance: number;
+	/** Metadata as JSON (using serde-json feature) */
+	metadata: Record<string, unknown>;
 }
 
 export interface TextSearchResult {
-  id: string
-  score: number
-  metadata: Record<string, unknown>
+	id: string;
+	score: number;
+	metadata: Record<string, unknown>;
 }
 
 export interface VectorItem {
-  id: string
-  /** Vector data as array of numbers */
-  vector: Array<number>
-  /** Optional metadata */
-  metadata?: Record<string, unknown> | undefined
-  /** Optional document text (stored in metadata.document) */
-  document?: string
+	id: string;
+	/** Vector data as array of numbers */
+	vector: Array<number>;
+	/** Optional metadata */
+	metadata?: Record<string, unknown> | undefined;
+	/** Optional document text (stored in metadata.document) */
+	document?: string;
 }
 
 export interface VectorItemWithText {
-  id: string
-  vector: Array<number>
-  text: string
-  metadata?: Record<string, unknown> | undefined
+	id: string;
+	vector: Array<number>;
+	text: string;
+	metadata?: Record<string, unknown> | undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Fast embedded vector database with HNSW indexing",
   "main": "index.js",
   "types": "index.d.ts",
@@ -49,9 +49,9 @@
     "omendb.node"
   ],
   "optionalDependencies": {
-    "@omendb/omendb-darwin-x64": "0.0.9",
-    "@omendb/omendb-darwin-arm64": "0.0.9",
-    "@omendb/omendb-linux-x64-gnu": "0.0.9",
-    "@omendb/omendb-linux-arm64-gnu": "0.0.9"
+    "@omendb/omendb-darwin-x64": "0.0.11",
+    "@omendb/omendb-darwin-arm64": "0.0.11",
+    "@omendb/omendb-linux-x64-gnu": "0.0.11",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.11"
   }
 }