JSCBC-1342: Support FTS like Pre-Filters while doing Vector Search

thejcfactor · thejcfactor · commit 1adf2fd81c55 · 2025-08-20T01:15:26.000Z
Changes ======= * Added prefilter option to `VectorQuery` * Updated search unit tests to confirm prefilter must be a `SearchQuery` * Added `TermRangeQuery` * Fixed `GeoDistanceQuery` distance param to be a string * Validated changes with FIT performer Change-Id: I9a5d6c4b998bea66c18a424ecc6673b406aeae4c Reviewed-on: https://review.couchbase.org/c/couchnode/+/232454 Reviewed-by: Mateusz <matt.wozakowski@couchbase.com> Tested-by: Jared Casey <jared.casey@couchbase.com>
diff --git a/lib/searchquery.ts b/lib/searchquery.ts
@@ -116,6 +116,10 @@ export class SearchQuery {
     return new DateRangeSearchQuery()
   }
 
+  static termRange(): TermRangeSearchQuery {
+    return new TermRangeSearchQuery()
+  }
+
   /**
    * Creates a ConjunctionSearchQuery from a set of other SearchQuery's.
    *
@@ -215,7 +219,7 @@ export class SearchQuery {
   static geoDistance(
     lon: number,
     lat: number,
-    distance: number
+    distance: string
   ): GeoDistanceSearchQuery {
     return new GeoDistanceSearchQuery(lon, lat, distance)
   }
@@ -461,6 +465,50 @@ export class DateRangeSearchQuery extends SearchQuery {
   }
 }
 
+/**
+ * Represents a term-range search query.
+ *
+ * @category Full Text Search
+ */
+export class TermRangeSearchQuery extends SearchQuery {
+  /**
+   * @internal
+   */
+  constructor() {
+    super({})
+  }
+
+  min(min: string, inclusive?: boolean): TermRangeSearchQuery {
+    if (inclusive === undefined) {
+      inclusive = true
+    }
+
+    this._data.min = min
+    this._data.inclusive_min = inclusive
+    return this
+  }
+
+  max(max: string, inclusive?: boolean): TermRangeSearchQuery {
+    if (inclusive === undefined) {
+      inclusive = false
+    }
+
+    this._data.max = max
+    this._data.inclusive_max = inclusive
+    return this
+  }
+
+  field(field: string): TermRangeSearchQuery {
+    this._data.field = field
+    return this
+  }
+
+  boost(boost: number): TermRangeSearchQuery {
+    this._data.boost = boost
+    return this
+  }
+}
+
 /**
  * Represents a conjunction search query.
  *
@@ -858,7 +906,7 @@ export class GeoDistanceSearchQuery extends SearchQuery {
   /**
    * @internal
    */
-  constructor(lon: number, lat: number, distance: number) {
+  constructor(lon: number, lat: number, distance: string) {
     super({
       location: [lon, lat],
       distance: distance,
diff --git a/lib/vectorsearch.ts b/lib/vectorsearch.ts
@@ -1,4 +1,5 @@
 import { InvalidArgumentError } from './errors'
+import { SearchQuery } from './searchquery'
 
 /**
  * Specifies how multiple vector searches are combined.
@@ -38,6 +39,7 @@ export class VectorQuery {
   private _vectorBase64: string | undefined
   private _numCandidates: number | undefined
   private _boost: number | undefined
+  private _prefilter: SearchQuery | undefined
 
   constructor(fieldName: string, vector: number[] | string) {
     if (!fieldName) {
@@ -83,6 +85,9 @@ export class VectorQuery {
     if (this._boost) {
       output['boost'] = this._boost
     }
+    if (this._prefilter) {
+      output['filter'] = this._prefilter.toJSON()
+    }
     return output
   }
 
@@ -111,6 +116,21 @@ export class VectorQuery {
     return this
   }
 
+  /**
+   * Adds prefilter option to vector query.
+   *
+   * @param prefilter A SearchQuery.
+   */
+  prefilter(prefilter: SearchQuery): VectorQuery {
+    if (!(prefilter instanceof SearchQuery)) {
+      throw new InvalidArgumentError(
+        new Error('Provided value for prefilter must be a SearchQuery.')
+      )
+    }
+    this._prefilter = prefilter
+    return this
+  }
+
   /**
    * Creates a vector query.
    *
diff --git a/test/search.test.js b/test/search.test.js
@@ -382,6 +382,10 @@ describe('#vectorsearch', function () {
       const vQuery = new VectorQuery('vector_field', testVector)
       vQuery.numCandidates(-1)
     }, H.lib.InvalidArgumentError)
+    assert.throws(() => {
+      const vQuery = new VectorQuery('vector_field', testVector)
+      vQuery.prefilter(new VectorQuery('vector_field1', testVector))
+    }, H.lib.InvalidArgumentError)
     assert.throws(() => {
       new VectorQuery('', testVector)
     }, H.lib.InvalidArgumentError)
