@lancedb/lancedb 0.19.0-beta.6 → 0.19.0-beta.8

package/dist/native.d.ts

@@ -208,7 +208,7 @@ export interface ConnectionOptions {
    * Note: this consistency only applies to read operations. Write operations are
    * always consistent.
    */
-  readConsistencyInterval?: number | null
+  readConsistencyInterval?: number
   /**
    * (For LanceDB OSS only): configuration for object storage.
    *
@@ -283,7 +283,7 @@ export class NativeMergeInsertBuilder {
 }
 export class Query {
   onlyIf(predicate: string): void
-  fullTextSearch(query: unknown): void
+  fullTextSearch(query: object): void
   select(columns: Array<[string, string]>): void
   selectColumns(columns: Array<string>): void
   limit(limit: number): void
@@ -306,7 +306,7 @@ export class VectorQuery {
   ef(ef: number): void
   bypassVectorIndex(): void
   onlyIf(predicate: string): void
-  fullTextSearch(query: unknown): void
+  fullTextSearch(query: object): void
   select(columns: Array<[string, string]>): void
   selectColumns(columns: Array<string>): void
   limit(limit: number): void
@@ -318,6 +318,12 @@ export class VectorQuery {
   explainPlan(verbose: boolean): Promise<string>
   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 boostQuery(positive: JsFullTextQuery, negative: JsFullTextQuery, negativeBoost?: number | undefined | null): JsFullTextQuery
+  static multiMatchQuery(query: string, columns: Array<string>, boosts?: Array<number> | undefined | null): JsFullTextQuery
+}
 /**
  * Reranker implementation that "wraps" a NodeJS Reranker implementation.
  * This contains references to the callbacks that can be used to invoke the
@@ -345,6 +351,7 @@ export class Table {
   delete(predicate: string): Promise<void>
   createIndex(index: Index | undefined | null, column: string, replace?: boolean | undefined | null): Promise<void>
   dropIndex(indexName: string): Promise<void>
+  prewarmIndex(indexName: string): Promise<void>
   update(onlyIf: string | undefined | null, columns: Array<[string, string]>): Promise<bigint>
   query(): Query
   vectorSearch(vector: Float32Array): VectorQuery

package/dist/native.js

@@ -319,13 +319,14 @@ if (!nativeBinding) {
     }
     throw new Error(`Failed to load native binding`);
 }
-const { Connection, Index, RecordBatchIterator, NativeMergeInsertBuilder, Query, VectorQuery, Reranker, RrfReranker, Table } = nativeBinding;
+const { Connection, Index, RecordBatchIterator, NativeMergeInsertBuilder, Query, VectorQuery, JsFullTextQuery, Reranker, RrfReranker, Table } = nativeBinding;
 module.exports.Connection = Connection;
 module.exports.Index = Index;
 module.exports.RecordBatchIterator = RecordBatchIterator;
 module.exports.NativeMergeInsertBuilder = NativeMergeInsertBuilder;
 module.exports.Query = Query;
 module.exports.VectorQuery = VectorQuery;
+module.exports.JsFullTextQuery = JsFullTextQuery;
 module.exports.Reranker = Reranker;
 module.exports.RrfReranker = RrfReranker;
 module.exports.Table = Table;

package/dist/query.d.ts

@@ -1,6 +1,6 @@
 import { Table as ArrowTable, type IntoVector, RecordBatch } from "./arrow";
 import { type IvfPqOptions } from "./indices";
-import { RecordBatchIterator as NativeBatchIterator, Query as NativeQuery, Table as NativeTable, VectorQuery as NativeVectorQuery } from "./native";
+import { JsFullTextQuery, RecordBatchIterator as NativeBatchIterator, Query as NativeQuery, Table as NativeTable, VectorQuery as NativeVectorQuery } from "./native";
 import { Reranker } from "./rerankers";
 export declare class RecordBatchIterator implements AsyncIterator<RecordBatch> {
     private promisedInner?;
@@ -412,31 +412,41 @@ export declare enum FullTextQueryType {
  * including methods to retrieve the query type and convert the query to a dictionary format.
  */
 export interface FullTextQuery {
+    /**
+     * Returns the inner query object.
+     * This is the underlying query object used by the database engine.
+     * @ignore
+     */
+    inner: JsFullTextQuery;
+    /**
+     * The type of the full-text query.
+     */
     queryType(): FullTextQueryType;
-    toDict(): Record<string, unknown>;
 }
+export declare function instanceOfFullTextQuery(obj: any): obj is FullTextQuery;
 export declare class MatchQuery implements FullTextQuery {
-    private query;
-    private column;
-    private boost;
-    private fuzziness;
-    private maxExpansions;
+    /** @ignore */
+    readonly inner: JsFullTextQuery;
     /**
      * Creates an instance of MatchQuery.
      *
      * @param query - The text query to search for.
      * @param column - The name of the column to search within.
-     * @param boost - (Optional) The boost factor to influence the relevance score of this query. Default is `1.0`.
-     * @param fuzziness - (Optional) The allowed edit distance for fuzzy matching. Default is `0`.
-     * @param maxExpansions - (Optional) The maximum number of terms to consider for fuzzy matching. Default is `50`.
+     * @param options - Optional parameters for the match query.
+     *   - `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).
      */
-    constructor(query: string, column: string, boost?: number, fuzziness?: number, maxExpansions?: number);
+    constructor(query: string, column: string, options?: {
+        boost?: number;
+        fuzziness?: number;
+        maxExpansions?: number;
+    });
     queryType(): FullTextQueryType;
-    toDict(): Record<string, unknown>;
 }
 export declare class PhraseQuery implements FullTextQuery {
-    private query;
-    private column;
+    /** @ignore */
+    readonly inner: JsFullTextQuery;
     /**
      * Creates an instance of `PhraseQuery`.
      *
@@ -445,38 +455,39 @@ export declare class PhraseQuery implements FullTextQuery {
      */
     constructor(query: string, column: string);
     queryType(): FullTextQueryType;
-    toDict(): Record<string, unknown>;
 }
 export declare class BoostQuery implements FullTextQuery {
-    private positive;
-    private negative;
-    private negativeBoost;
+    /** @ignore */
+    readonly inner: JsFullTextQuery;
     /**
      * Creates an instance of BoostQuery.
+     * The boost returns documents that match the positive query,
+     * but penalizes those that match the negative query.
+     * the penalty is controlled by the `negativeBoost` parameter.
      *
      * @param positive - The positive query that boosts the relevance score.
      * @param negative - The negative query that reduces the relevance score.
-     * @param negativeBoost - The factor by which the negative query reduces the score.
+     * @param options - Optional parameters for the boost query.
+     *  - `negativeBoost`: The boost factor for the negative query (default is 0.0).
      */
-    constructor(positive: FullTextQuery, negative: FullTextQuery, negativeBoost: number);
+    constructor(positive: FullTextQuery, negative: FullTextQuery, options?: {
+        negativeBoost?: number;
+    });
     queryType(): FullTextQueryType;
-    toDict(): Record<string, unknown>;
 }
 export declare class MultiMatchQuery implements FullTextQuery {
-    private query;
-    private columns;
-    private boosts;
+    /** @ignore */
+    readonly inner: JsFullTextQuery;
     /**
      * Creates an instance of MultiMatchQuery.
      *
      * @param query - The text query to search for across multiple columns.
      * @param columns - An array of column names to search within.
-     * @param boosts - (Optional) An array of boost factors corresponding to each column. Default is an array of 1.0 for each column.
-     *
-     * The `boosts` array should have the same length as `columns`. If not provided, all columns will have a default boost of 1.0.
-     * If the length of `boosts` is less than `columns`, it will be padded with 1.0s.
+     * @param options - Optional parameters for the multi-match query.
+     *  - `boosts`: An array of boost factors for each column (default is 1.0 for all).
      */
-    constructor(query: string, columns: string[], boosts?: number[]);
+    constructor(query: string, columns: string[], options?: {
+        boosts?: number[];
+    });
     queryType(): FullTextQueryType;
-    toDict(): Record<string, unknown>;
 }

package/dist/query.js

@@ -3,7 +3,9 @@
 // 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.instanceOfFullTextQuery = instanceOfFullTextQuery;
 const arrow_1 = require("./arrow");
+const native_1 = require("./native");
 class RecordBatchIterator {
     promisedInner;
     inner;
@@ -117,9 +119,7 @@ class QueryBase {
                 });
             }
             else {
-                // If query is a FullTextQuery object, convert it to a dict
-                const queryObj = query.toDict();
-                inner.fullTextSearch(queryObj);
+                inner.fullTextSearch({ query: query.inner });
             }
         });
         return this;
@@ -640,8 +640,7 @@ class Query extends QueryBase {
                 });
             }
             else {
-                const queryObj = query.toDict();
-                inner.fullTextSearch(queryObj);
+                inner.fullTextSearch({ query: query.inner });
             }
         });
         return this;
@@ -663,49 +662,38 @@ var FullTextQueryType;
     FullTextQueryType["Boost"] = "boost";
     FullTextQueryType["MultiMatch"] = "multi_match";
 })(FullTextQueryType || (exports.FullTextQueryType = FullTextQueryType = {}));
+// biome-ignore lint/suspicious/noExplicitAny: we want any here
+function instanceOfFullTextQuery(obj) {
+    return obj != null && obj.inner instanceof native_1.JsFullTextQuery;
+}
 class MatchQuery {
-    query;
-    column;
-    boost;
-    fuzziness;
-    maxExpansions;
+    /** @ignore */
+    inner;
     /**
      * Creates an instance of MatchQuery.
      *
      * @param query - The text query to search for.
      * @param column - The name of the column to search within.
-     * @param boost - (Optional) The boost factor to influence the relevance score of this query. Default is `1.0`.
-     * @param fuzziness - (Optional) The allowed edit distance for fuzzy matching. Default is `0`.
-     * @param maxExpansions - (Optional) The maximum number of terms to consider for fuzzy matching. Default is `50`.
+     * @param options - Optional parameters for the match query.
+     *   - `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).
      */
-    constructor(query, column, boost = 1.0, fuzziness = 0, maxExpansions = 50) {
-        this.query = query;
-        this.column = column;
-        this.boost = boost;
-        this.fuzziness = fuzziness;
-        this.maxExpansions = maxExpansions;
+    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);
     }
     queryType() {
         return FullTextQueryType.Match;
     }
-    toDict() {
-        return {
-            [this.queryType()]: {
-                [this.column]: {
-                    query: this.query,
-                    boost: this.boost,
-                    fuzziness: this.fuzziness,
-                    // biome-ignore lint/style/useNamingConvention: use underscore for consistency with the other APIs
-                    max_expansions: this.maxExpansions,
-                },
-            },
-        };
-    }
 }
 exports.MatchQuery = MatchQuery;
 class PhraseQuery {
-    query;
-    column;
+    /** @ignore */
+    inner;
     /**
      * Creates an instance of `PhraseQuery`.
      *
@@ -713,82 +701,51 @@ class PhraseQuery {
      * @param column - The name of the column to search within.
      */
     constructor(query, column) {
-        this.query = query;
-        this.column = column;
+        this.inner = native_1.JsFullTextQuery.phraseQuery(query, column);
     }
     queryType() {
         return FullTextQueryType.MatchPhrase;
     }
-    toDict() {
-        return {
-            [this.queryType()]: {
-                [this.column]: this.query,
-            },
-        };
-    }
 }
 exports.PhraseQuery = PhraseQuery;
 class BoostQuery {
-    positive;
-    negative;
-    negativeBoost;
+    /** @ignore */
+    inner;
     /**
      * Creates an instance of BoostQuery.
+     * The boost returns documents that match the positive query,
+     * but penalizes those that match the negative query.
+     * the penalty is controlled by the `negativeBoost` parameter.
      *
      * @param positive - The positive query that boosts the relevance score.
      * @param negative - The negative query that reduces the relevance score.
-     * @param negativeBoost - The factor by which the negative query reduces the score.
+     * @param options - Optional parameters for the boost query.
+     *  - `negativeBoost`: The boost factor for the negative query (default is 0.0).
      */
-    constructor(positive, negative, negativeBoost) {
-        this.positive = positive;
-        this.negative = negative;
-        this.negativeBoost = negativeBoost;
+    constructor(positive, negative, options) {
+        this.inner = native_1.JsFullTextQuery.boostQuery(positive.inner, negative.inner, options?.negativeBoost);
     }
     queryType() {
         return FullTextQueryType.Boost;
     }
-    toDict() {
-        return {
-            [this.queryType()]: {
-                positive: this.positive.toDict(),
-                negative: this.negative.toDict(),
-                // biome-ignore lint/style/useNamingConvention: use underscore for consistency with the other APIs
-                negative_boost: this.negativeBoost,
-            },
-        };
-    }
 }
 exports.BoostQuery = BoostQuery;
 class MultiMatchQuery {
-    query;
-    columns;
-    boosts;
+    /** @ignore */
+    inner;
     /**
      * Creates an instance of MultiMatchQuery.
      *
      * @param query - The text query to search for across multiple columns.
      * @param columns - An array of column names to search within.
-     * @param boosts - (Optional) An array of boost factors corresponding to each column. Default is an array of 1.0 for each column.
-     *
-     * The `boosts` array should have the same length as `columns`. If not provided, all columns will have a default boost of 1.0.
-     * If the length of `boosts` is less than `columns`, it will be padded with 1.0s.
+     * @param options - Optional parameters for the multi-match query.
+     *  - `boosts`: An array of boost factors for each column (default is 1.0 for all).
      */
-    constructor(query, columns, boosts = columns.map(() => 1.0)) {
-        this.query = query;
-        this.columns = columns;
-        this.boosts = boosts;
+    constructor(query, columns, options) {
+        this.inner = native_1.JsFullTextQuery.multiMatchQuery(query, columns, options?.boosts);
     }
     queryType() {
         return FullTextQueryType.MultiMatch;
     }
-    toDict() {
-        return {
-            [this.queryType()]: {
-                query: this.query,
-                columns: this.columns,
-                boost: this.boosts,
-            },
-        };
-    }
 }
 exports.MultiMatchQuery = MultiMatchQuery;

package/dist/table.d.ts

@@ -2,7 +2,7 @@ import { Table as ArrowTable, Data, DataType, IntoVector, Schema } from "./arrow
 import { IndexOptions } from "./indices";
 import { MergeInsertBuilder } from "./merge";
 import { AddColumnsSql, IndexConfig, IndexStatistics, OptimizeStats, Table as _NativeTable } from "./native";
-import { Query, VectorQuery } from "./query";
+import { FullTextQuery, Query, VectorQuery } from "./query";
 import { IntoSql } from "./util";
 export { IndexConfig } from "./native";
 /**
@@ -187,6 +187,16 @@ export declare abstract class Table {
      * Use {@link Table.listIndices} to find the names of the indices.
      */
     abstract dropIndex(name: string): Promise<void>;
+    /**
+     * Prewarm an index in the table.
+     *
+     * @param name The name of the index.
+     *
+     * This will load the index into memory.  This may reduce the cold-start time for
+     * future queries.  If the index does not fit in the cache then this call may be
+     * wasteful.
+     */
+    abstract prewarmIndex(name: string): Promise<void>;
     /**
      * Create a {@link Query} Builder.
      *
@@ -249,7 +259,7 @@ export declare abstract class Table {
      * when "auto" is used, if the query is a string and an embedding function is defined, it will be treated as a vector query
      * if the query is a string and no embedding function is defined, it will be treated as a full text search query
      */
-    abstract search(query: string | IntoVector, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
+    abstract search(query: string | IntoVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
     /**
      * Search the table with a given query vector.
      *
@@ -401,8 +411,9 @@ export declare class LocalTable extends Table {
     delete(predicate: string): Promise<void>;
     createIndex(column: string, options?: Partial<IndexOptions>): Promise<void>;
     dropIndex(name: string): Promise<void>;
+    prewarmIndex(name: string): Promise<void>;
     query(): Query;
-    search(query: string | IntoVector, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
+    search(query: string | IntoVector | FullTextQuery, queryType?: string, ftsColumns?: string | string[]): VectorQuery | Query;
     vectorSearch(vector: IntoVector): VectorQuery;
     addColumns(newColumnTransforms: AddColumnsSql[]): Promise<void>;
     alterColumns(columnAlterations: ColumnAlteration[]): Promise<void>;

package/dist/table.js

@@ -128,11 +128,14 @@ class LocalTable extends Table {
     async dropIndex(name) {
         await this.inner.dropIndex(name);
     }
+    async prewarmIndex(name) {
+        await this.inner.prewarmIndex(name);
+    }
     query() {
         return new query_1.Query(this.inner);
     }
     search(query, queryType = "auto", ftsColumns) {
-        if (typeof query !== "string") {
+        if (typeof query !== "string" && !(0, query_1.instanceOfFullTextQuery)(query)) {
             if (queryType === "fts") {
                 throw new Error("Cannot perform full text search on a vector query");
             }
@@ -146,7 +149,8 @@ class LocalTable extends Table {
         }
         // The query type is auto or vector
         // fall back to full text search if no embedding functions are defined and the query is a string
-        if (queryType === "auto" && (0, registry_1.getRegistry)().length() === 0) {
+        if (queryType === "auto" &&
+            ((0, registry_1.getRegistry)().length() === 0 || (0, query_1.instanceOfFullTextQuery)(query))) {
             return this.query().fullTextSearch(query, {
                 columns: ftsColumns,
             });

package/package.json

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