@lancedb/lancedb 0.20.0 → 0.20.1-beta.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { ConnectionOptions } from "./native.js";
 export { AddColumnsSql, ConnectionOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, MergeResult, AddResult, AddColumnsResult, AlterColumnsResult, DeleteResult, DropColumnsResult, UpdateResult, } from "./native.js";
 export { makeArrowTable, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
 export { Connection, CreateTableOptions, TableNamesOptions, OpenTableOptions, } from "./connection";
-export { ExecutableQuery, Query, QueryBase, VectorQuery, QueryExecutionOptions, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, FullTextQueryType, } from "./query";
+export { ExecutableQuery, Query, QueryBase, VectorQuery, QueryExecutionOptions, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
 export { Index, IndexOptions, IvfPqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, } from "./indices";
 export { Table, AddDataOptions, UpdateOptions, OptimizeOptions, Version, ColumnAlteration, } from "./table";
 export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";

package/dist/index.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.packBits = exports.rerankers = exports.embedding = exports.MergeInsertBuilder = exports.Table = exports.Index = exports.FullTextQueryType = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = void 0;
+exports.packBits = exports.rerankers = exports.embedding = exports.MergeInsertBuilder = exports.Table = exports.Index = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = exports.TagContents = exports.Tags = void 0;
 exports.connect = connect;
 const connection_1 = require("./connection");
 const native_js_1 = require("./native.js");
@@ -24,7 +24,10 @@ Object.defineProperty(exports, "MatchQuery", { enumerable: true, get: function (
 Object.defineProperty(exports, "PhraseQuery", { enumerable: true, get: function () { return query_1.PhraseQuery; } });
 Object.defineProperty(exports, "BoostQuery", { enumerable: true, get: function () { return query_1.BoostQuery; } });
 Object.defineProperty(exports, "MultiMatchQuery", { enumerable: true, get: function () { return query_1.MultiMatchQuery; } });
+Object.defineProperty(exports, "BooleanQuery", { enumerable: true, get: function () { return query_1.BooleanQuery; } });
 Object.defineProperty(exports, "FullTextQueryType", { enumerable: true, get: function () { return query_1.FullTextQueryType; } });
+Object.defineProperty(exports, "Operator", { enumerable: true, get: function () { return query_1.Operator; } });
+Object.defineProperty(exports, "Occur", { enumerable: true, get: function () { return query_1.Occur; } });
 var indices_1 = require("./indices");
 Object.defineProperty(exports, "Index", { enumerable: true, get: function () { return indices_1.Index; } });
 var table_1 = require("./table");

package/dist/native.d.ts

@@ -362,6 +362,8 @@ export class VectorQuery {
   postfilter(): void
   refineFactor(refineFactor: number): void
   nprobes(nprobe: number): void
+  minimumNprobes(minimumNprobe: number): void
+  maximumNprobes(maximumNprobes: number): void
   distanceRange(lowerBound?: number | undefined | null, upperBound?: number | undefined | null): void
   ef(ef: number): void
   bypassVectorIndex(): void
@@ -379,10 +381,12 @@ export class VectorQuery {
   analyzePlan(): Promise<string>
 }
 export class JsFullTextQuery {
-  static matchQuery(query: string, column: string, boost: number, fuzziness: number | undefined | null, maxExpansions: number): JsFullTextQuery
-  static phraseQuery(query: string, column: string): JsFullTextQuery
+  static matchQuery(query: string, column: string, boost: number, fuzziness: number | undefined | null, maxExpansions: number, operator: string): JsFullTextQuery
+  static phraseQuery(query: string, column: string, slop: number): JsFullTextQuery
   static boostQuery(positive: JsFullTextQuery, negative: JsFullTextQuery, negativeBoost?: number | undefined | null): JsFullTextQuery
-  static multiMatchQuery(query: string, columns: Array<string>, boosts?: Array<number> | undefined | null): JsFullTextQuery
+  static multiMatchQuery(query: string, columns: Array<string>, boosts: Array<number> | undefined | null, operator: string): JsFullTextQuery
+  static booleanQuery(queries: Array<[string, JsFullTextQuery]>): JsFullTextQuery
+  get queryType(): string
 }
 /**
  * Reranker implementation that "wraps" a NodeJS Reranker implementation.

package/dist/query.d.ts

@@ -239,8 +239,31 @@ export declare class VectorQuery extends QueryBase<NativeVectorQuery> {
      * For best results we recommend tuning this parameter with a benchmark against
      * your actual data to find the smallest possible value that will still give
      * you the desired recall.
+     *
+     * For more fine grained control over behavior when you have a very narrow filter
+     * you can use `minimumNprobes` and `maximumNprobes`.  This method sets both
+     * the minimum and maximum to the same value.
      */
     nprobes(nprobes: number): VectorQuery;
+    /**
+     * Set the minimum number of probes used.
+     *
+     * This controls the minimum number of partitions that will be searched.  This
+     * parameter will impact every query against a vector index, regardless of the
+     * filter.  See `nprobes` for more details.  Higher values will increase recall
+     * but will also increase latency.
+     */
+    minimumNprobes(minimumNprobes: number): VectorQuery;
+    /**
+     * Set the maximum number of probes used.
+     *
+     * This controls the maximum number of partitions that will be searched.  If this
+     * number is greater than minimumNprobes then the excess partitions will _only_ be
+     * searched if we have not found enough results.  This can be useful when there is
+     * a narrow filter to allow these queries to spend more time searching and avoid
+     * potential false negatives.
+     */
+    maximumNprobes(maximumNprobes: number): VectorQuery;
     distanceRange(lowerBound?: number, upperBound?: number): VectorQuery;
     /**
      * Set the number of candidates to consider during the search
@@ -404,7 +427,28 @@ export declare enum FullTextQueryType {
     Match = "match",
     MatchPhrase = "match_phrase",
     Boost = "boost",
-    MultiMatch = "multi_match"
+    MultiMatch = "multi_match",
+    Boolean = "boolean"
+}
+/**
+ * Enum representing the logical operators used in full-text queries.
+ *
+ * - `And`: All terms must match.
+ * - `Or`: At least one term must match.
+ */
+export declare enum Operator {
+    And = "AND",
+    Or = "OR"
+}
+/**
+ * Enum representing the occurrence of terms in full-text queries.
+ *
+ * - `Must`: The term must be present in the document.
+ * - `Should`: The term should contribute to the document score, but is not required.
+ */
+export declare enum Occur {
+    Must = "MUST",
+    Should = "SHOULD"
 }
 /**
  * Represents a full-text query interface.
@@ -436,11 +480,13 @@ export declare class MatchQuery implements FullTextQuery {
      *   - `boost`: The boost factor for the query (default is 1.0).
      *   - `fuzziness`: The fuzziness level for the query (default is 0).
      *   - `maxExpansions`: The maximum number of terms to consider for fuzzy matching (default is 50).
+     *   - `operator`: The logical operator to use for combining terms in the query (default is "OR").
      */
     constructor(query: string, column: string, options?: {
         boost?: number;
         fuzziness?: number;
         maxExpansions?: number;
+        operator?: Operator;
     });
     queryType(): FullTextQueryType;
 }
@@ -452,8 +498,12 @@ export declare class PhraseQuery implements FullTextQuery {
      *
      * @param query - The phrase to search for in the specified column.
      * @param column - The name of the column to search within.
+     * @param options - Optional parameters for the phrase query.
+     *   - `slop`: The maximum number of intervening unmatched positions allowed between words in the phrase (default is 0).
      */
-    constructor(query: string, column: string);
+    constructor(query: string, column: string, options?: {
+        slop?: number;
+    });
     queryType(): FullTextQueryType;
 }
 export declare class BoostQuery implements FullTextQuery {
@@ -485,9 +535,23 @@ export declare class MultiMatchQuery implements FullTextQuery {
      * @param columns - An array of column names to search within.
      * @param options - Optional parameters for the multi-match query.
      *  - `boosts`: An array of boost factors for each column (default is 1.0 for all).
+     *  - `operator`: The logical operator to use for combining terms in the query (default is "OR").
      */
     constructor(query: string, columns: string[], options?: {
         boosts?: number[];
+        operator?: Operator;
     });
     queryType(): FullTextQueryType;
 }
+export declare class BooleanQuery implements FullTextQuery {
+    /** @ignore */
+    readonly inner: JsFullTextQuery;
+    /**
+     * Creates an instance of BooleanQuery.
+     *
+     * @param queries - An array of (Occur, FullTextQuery objects) to combine.
+     * Occur specifies whether the query must match, or should match.
+     */
+    constructor(queries: [Occur, FullTextQuery][]);
+    queryType(): FullTextQueryType;
+}

package/dist/query.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.FullTextQueryType = exports.Query = exports.VectorQuery = exports.QueryBase = exports.RecordBatchIterator = void 0;
+exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.Query = exports.VectorQuery = exports.QueryBase = exports.RecordBatchIterator = void 0;
 exports.instanceOfFullTextQuery = instanceOfFullTextQuery;
 const arrow_1 = require("./arrow");
 const native_1 = require("./native");
@@ -366,11 +366,40 @@ class VectorQuery extends QueryBase {
      * For best results we recommend tuning this parameter with a benchmark against
      * your actual data to find the smallest possible value that will still give
      * you the desired recall.
+     *
+     * For more fine grained control over behavior when you have a very narrow filter
+     * you can use `minimumNprobes` and `maximumNprobes`.  This method sets both
+     * the minimum and maximum to the same value.
      */
     nprobes(nprobes) {
         super.doCall((inner) => inner.nprobes(nprobes));
         return this;
     }
+    /**
+     * Set the minimum number of probes used.
+     *
+     * This controls the minimum number of partitions that will be searched.  This
+     * parameter will impact every query against a vector index, regardless of the
+     * filter.  See `nprobes` for more details.  Higher values will increase recall
+     * but will also increase latency.
+     */
+    minimumNprobes(minimumNprobes) {
+        super.doCall((inner) => inner.minimumNprobes(minimumNprobes));
+        return this;
+    }
+    /**
+     * Set the maximum number of probes used.
+     *
+     * This controls the maximum number of partitions that will be searched.  If this
+     * number is greater than minimumNprobes then the excess partitions will _only_ be
+     * searched if we have not found enough results.  This can be useful when there is
+     * a narrow filter to allow these queries to spend more time searching and avoid
+     * potential false negatives.
+     */
+    maximumNprobes(maximumNprobes) {
+        super.doCall((inner) => inner.maximumNprobes(maximumNprobes));
+        return this;
+    }
     /*
      * Set the distance range to use
      *
@@ -661,7 +690,30 @@ var FullTextQueryType;
     FullTextQueryType["MatchPhrase"] = "match_phrase";
     FullTextQueryType["Boost"] = "boost";
     FullTextQueryType["MultiMatch"] = "multi_match";
+    FullTextQueryType["Boolean"] = "boolean";
 })(FullTextQueryType || (exports.FullTextQueryType = FullTextQueryType = {}));
+/**
+ * Enum representing the logical operators used in full-text queries.
+ *
+ * - `And`: All terms must match.
+ * - `Or`: At least one term must match.
+ */
+var Operator;
+(function (Operator) {
+    Operator["And"] = "AND";
+    Operator["Or"] = "OR";
+})(Operator || (exports.Operator = Operator = {}));
+/**
+ * Enum representing the occurrence of terms in full-text queries.
+ *
+ * - `Must`: The term must be present in the document.
+ * - `Should`: The term should contribute to the document score, but is not required.
+ */
+var Occur;
+(function (Occur) {
+    Occur["Must"] = "MUST";
+    Occur["Should"] = "SHOULD";
+})(Occur || (exports.Occur = Occur = {}));
 // biome-ignore lint/suspicious/noExplicitAny: we want any here
 function instanceOfFullTextQuery(obj) {
     return obj != null && obj.inner instanceof native_1.JsFullTextQuery;
@@ -678,13 +730,14 @@ class MatchQuery {
      *   - `boost`: The boost factor for the query (default is 1.0).
      *   - `fuzziness`: The fuzziness level for the query (default is 0).
      *   - `maxExpansions`: The maximum number of terms to consider for fuzzy matching (default is 50).
+     *   - `operator`: The logical operator to use for combining terms in the query (default is "OR").
      */
     constructor(query, column, options) {
         let fuzziness = options?.fuzziness;
         if (fuzziness === undefined) {
             fuzziness = 0;
         }
-        this.inner = native_1.JsFullTextQuery.matchQuery(query, column, options?.boost ?? 1.0, fuzziness, options?.maxExpansions ?? 50);
+        this.inner = native_1.JsFullTextQuery.matchQuery(query, column, options?.boost ?? 1.0, fuzziness, options?.maxExpansions ?? 50, options?.operator ?? Operator.Or);
     }
     queryType() {
         return FullTextQueryType.Match;
@@ -699,9 +752,11 @@ class PhraseQuery {
      *
      * @param query - The phrase to search for in the specified column.
      * @param column - The name of the column to search within.
+     * @param options - Optional parameters for the phrase query.
+     *   - `slop`: The maximum number of intervening unmatched positions allowed between words in the phrase (default is 0).
      */
-    constructor(query, column) {
-        this.inner = native_1.JsFullTextQuery.phraseQuery(query, column);
+    constructor(query, column, options) {
+        this.inner = native_1.JsFullTextQuery.phraseQuery(query, column, options?.slop ?? 0);
     }
     queryType() {
         return FullTextQueryType.MatchPhrase;
@@ -740,12 +795,30 @@ class MultiMatchQuery {
      * @param columns - An array of column names to search within.
      * @param options - Optional parameters for the multi-match query.
      *  - `boosts`: An array of boost factors for each column (default is 1.0 for all).
+     *  - `operator`: The logical operator to use for combining terms in the query (default is "OR").
      */
     constructor(query, columns, options) {
-        this.inner = native_1.JsFullTextQuery.multiMatchQuery(query, columns, options?.boosts);
+        this.inner = native_1.JsFullTextQuery.multiMatchQuery(query, columns, options?.boosts, options?.operator ?? Operator.Or);
     }
     queryType() {
         return FullTextQueryType.MultiMatch;
     }
 }
 exports.MultiMatchQuery = MultiMatchQuery;
+class BooleanQuery {
+    /** @ignore */
+    inner;
+    /**
+     * Creates an instance of BooleanQuery.
+     *
+     * @param queries - An array of (Occur, FullTextQuery objects) to combine.
+     * Occur specifies whether the query must match, or should match.
+     */
+    constructor(queries) {
+        this.inner = native_1.JsFullTextQuery.booleanQuery(queries.map(([occur, query]) => [occur, query.inner]));
+    }
+    queryType() {
+        return FullTextQueryType.Boolean;
+    }
+}
+exports.BooleanQuery = BooleanQuery;

package/package.json

@@ -11,7 +11,7 @@
     "ann"
   ],
   "private": false,
-  "version": "0.20.0",
+  "version": "0.20.1-beta.0",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -100,14 +100,14 @@
     "reflect-metadata": "^0.2.2"
   },
   "optionalDependencies": {
-    "@lancedb/lancedb-darwin-x64": "0.20.0",
-    "@lancedb/lancedb-darwin-arm64": "0.20.0",
-    "@lancedb/lancedb-linux-x64-gnu": "0.20.0",
-    "@lancedb/lancedb-linux-arm64-gnu": "0.20.0",
-    "@lancedb/lancedb-linux-x64-musl": "0.20.0",
-    "@lancedb/lancedb-linux-arm64-musl": "0.20.0",
-    "@lancedb/lancedb-win32-x64-msvc": "0.20.0",
-    "@lancedb/lancedb-win32-arm64-msvc": "0.20.0"
+    "@lancedb/lancedb-darwin-x64": "0.20.1-beta.0",
+    "@lancedb/lancedb-darwin-arm64": "0.20.1-beta.0",
+    "@lancedb/lancedb-linux-x64-gnu": "0.20.1-beta.0",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.20.1-beta.0",
+    "@lancedb/lancedb-linux-x64-musl": "0.20.1-beta.0",
+    "@lancedb/lancedb-linux-arm64-musl": "0.20.1-beta.0",
+    "@lancedb/lancedb-win32-x64-msvc": "0.20.1-beta.0",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.20.1-beta.0"
   },
   "peerDependencies": {
     "apache-arrow": ">=15.0.0 <=18.1.0"