docs(node): clarify full-text search filtering

nodejs/examples/filtering.test.ts

@@ -47,5 +47,22 @@ test("filtering examples", async () => {
       .limit(5)
       .toArray();
     // --8<-- [end:orderby_search]
+
+    const ftsTable = await db.createTable("myFts", [
+      { text: "Frodo was a happy puppy", category: "pet" },
+      { text: "A puppy training guide", category: "guide" },
+      { text: "There are several kittens playing", category: "pet" },
+    ]);
+    await ftsTable.createIndex("text", { config: lancedb.Index.fts() });
+
+    // --8<-- [start:fts_prefilter]
+    const ftsResults = await ftsTable
+      .search("puppy", "fts")
+      .where("category = 'pet'")
+      .limit(10)
+      .toArray();
+    // --8<-- [end:fts_prefilter]
+    expect(ftsResults).toHaveLength(1);
+    expect(ftsResults[0].category).toBe("pet");
   });
 });

nodejs/lancedb/query.ts

@@ -363,17 +363,33 @@ export class StandardQueryBase<
   /**
    * A filter statement to be applied to this query.
    *
-   * The filter should be supplied as an SQL query string.  For example:
-   * @example
-   * x > 10
-   * y > 0 AND y < 100
-   * x > 5 OR y = 'test'
+   * Filters are applied before full-text and vector searches by default; no
+   * separate prefilter call is needed. For vector searches only, use
+   * {@link VectorQuery#postfilter} to apply the filter after the search.
+   *
+   * The filter should be supplied as an SQL query string.
    *
    * Filtering performance can often be improved by creating a scalar index
    * on the filter column(s).
    *
    * Calling this multiple times combines the filters with a logical AND rather
    * than replacing the previous filter.
+   *
+   * @example Filter a full-text search
+   * ```ts
+   * const results = await table
+   *   .search("puppy", "fts")
+   *   .where("meta = 'foo'")
+   *   .limit(10)
+   *   .toArray();
+   * ```
+   *
+   * @example SQL filter expressions
+   * ```ts
+   * query.where("x > 10");
+   * query.where("y > 0 AND y < 100");
+   * query.where("x > 5 OR y = 'test'");
+   * ```
    */
   where(predicate: string): this {
     this.doCall((inner: NativeQueryType) => inner.onlyIf(predicate));
@@ -669,6 +685,9 @@ export class VectorQuery extends StandardQueryBase<NativeVectorQuery> {
    * If this is called then filtering will happen after the vector search instead of
    * before.
    *
+   * This method is only available for vector search queries. Full-text search
+   * filters are always applied before the search.
+   *
    * By default filtering will be performed before the vector search.  This is how
    * filtering is typically understood to work.  This prefilter step does add some
    * additional latency.  Creating a scalar index on the filter column(s) can