@lancedb/lancedb 0.18.3-beta.0 → 0.19.0-beta.3

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, } 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, } from "./query";
+export { ExecutableQuery, Query, QueryBase, VectorQuery, QueryExecutionOptions, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, FullTextQueryType, } from "./query";
 export { Index, IndexOptions, IvfPqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, } from "./indices";
 export { Table, AddDataOptions, UpdateOptions, OptimizeOptions, Version, ColumnAlteration, } from "./table";
 export { MergeInsertBuilder } 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.RecordBatchIterator = exports.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = void 0;
+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 = void 0;
 exports.connect = connect;
 const connection_1 = require("./connection");
 const native_js_1 = require("./native.js");
@@ -17,6 +17,11 @@ Object.defineProperty(exports, "Query", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "QueryBase", { enumerable: true, get: function () { return query_1.QueryBase; } });
 Object.defineProperty(exports, "VectorQuery", { enumerable: true, get: function () { return query_1.VectorQuery; } });
 Object.defineProperty(exports, "RecordBatchIterator", { enumerable: true, get: function () { return query_1.RecordBatchIterator; } });
+Object.defineProperty(exports, "MatchQuery", { enumerable: true, get: function () { return query_1.MatchQuery; } });
+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, "FullTextQueryType", { enumerable: true, get: function () { return query_1.FullTextQueryType; } });
 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

@@ -208,7 +208,7 @@ export interface ConnectionOptions {
    * Note: this consistency only applies to read operations. Write operations are
    * always consistent.
    */
-  readConsistencyInterval?: number
+  readConsistencyInterval?: number | null
   /**
    * (For LanceDB OSS only): configuration for object storage.
    *
@@ -283,7 +283,7 @@ export class NativeMergeInsertBuilder {
 }
 export class Query {
   onlyIf(predicate: string): void
-  fullTextSearch(query: string, columns?: Array<string> | undefined | null): void
+  fullTextSearch(query: unknown): void
   select(columns: Array<[string, string]>): void
   selectColumns(columns: Array<string>): void
   limit(limit: number): void
@@ -293,6 +293,7 @@ export class Query {
   withRowId(): void
   execute(maxBatchLength?: number | undefined | null): Promise<RecordBatchIterator>
   explainPlan(verbose: boolean): Promise<string>
+  analyzePlan(): Promise<string>
 }
 export class VectorQuery {
   column(column: string): void
@@ -305,7 +306,7 @@ export class VectorQuery {
   ef(ef: number): void
   bypassVectorIndex(): void
   onlyIf(predicate: string): void
-  fullTextSearch(query: string, columns?: Array<string> | undefined | null): void
+  fullTextSearch(query: unknown): void
   select(columns: Array<[string, string]>): void
   selectColumns(columns: Array<string>): void
   limit(limit: number): void
@@ -315,6 +316,7 @@ export class VectorQuery {
   rerank(callbacks: RerankerCallbacks): void
   execute(maxBatchLength?: number | undefined | null): Promise<RecordBatchIterator>
   explainPlan(verbose: boolean): Promise<string>
+  analyzePlan(): Promise<string>
 }
 /**
  * Reranker implementation that "wraps" a NodeJS Reranker implementation.

package/dist/query.d.ts

@@ -68,7 +68,7 @@ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVecto
      * @deprecated Use `where` instead
      */
     filter(predicate: string): this;
-    fullTextSearch(query: string, options?: Partial<FullTextSearchOptions>): this;
+    fullTextSearch(query: string | FullTextQuery, options?: Partial<FullTextSearchOptions>): this;
     /**
      * Return only the specified columns.
      *
@@ -162,6 +162,36 @@ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVecto
      * @returns A Promise that resolves to a string containing the query execution plan explanation.
      */
     explainPlan(verbose?: boolean): Promise<string>;
+    /**
+     * Executes the query and returns the physical query plan annotated with runtime metrics.
+     *
+     * This is useful for debugging and performance analysis, as it shows how the query was executed
+     * and includes metrics such as elapsed time, rows processed, and I/O statistics.
+     *
+     * @example
+     * import * as lancedb from "@lancedb/lancedb"
+     *
+     * const db = await lancedb.connect("./.lancedb");
+     * const table = await db.createTable("my_table", [
+     *   { vector: [1.1, 0.9], id: "1" },
+     * ]);
+     *
+     * const plan = await table.query().nearestTo([0.5, 0.2]).analyzePlan();
+     *
+     * Example output (with runtime metrics inlined):
+     * AnalyzeExec verbose=true, metrics=[]
+     *  ProjectionExec: expr=[id@3 as id, vector@0 as vector, _distance@2 as _distance], metrics=[output_rows=1, elapsed_compute=3.292µs]
+     *   Take: columns="vector, _rowid, _distance, (id)", metrics=[output_rows=1, elapsed_compute=66.001µs, batches_processed=1, bytes_read=8, iops=1, requests=1]
+     *    CoalesceBatchesExec: target_batch_size=1024, metrics=[output_rows=1, elapsed_compute=3.333µs]
+     *     GlobalLimitExec: skip=0, fetch=10, metrics=[output_rows=1, elapsed_compute=167ns]
+     *      FilterExec: _distance@2 IS NOT NULL, metrics=[output_rows=1, elapsed_compute=8.542µs]
+     *       SortExec: TopK(fetch=10), expr=[_distance@2 ASC NULLS LAST], metrics=[output_rows=1, elapsed_compute=63.25µs, row_replacements=1]
+     *        KNNVectorDistance: metric=l2, metrics=[output_rows=1, elapsed_compute=114.333µs, output_batches=1]
+     *         LanceScan: uri=/path/to/data, projection=[vector], row_id=true, row_addr=false, ordered=false, metrics=[output_rows=1, elapsed_compute=103.626µs, bytes_read=549, iops=2, requests=2]
+     *
+     * @returns A query execution plan with runtime metrics for each step.
+     */
+    analyzePlan(): Promise<string>;
 }
 /**
  * An interface for a query that can be executed
@@ -356,5 +386,93 @@ export declare class Query extends QueryBase<NativeQuery> {
      * a default `limit` of 10 will be used.  @see {@link Query#limit}
      */
     nearestTo(vector: IntoVector): VectorQuery;
-    nearestToText(query: string, columns?: string[]): Query;
+    nearestToText(query: string | FullTextQuery, columns?: string[]): Query;
+}
+/**
+ * Enum representing the types of full-text queries supported.
+ *
+ * - `Match`: Performs a full-text search for terms in the query string.
+ * - `MatchPhrase`: Searches for an exact phrase match in the text.
+ * - `Boost`: Boosts the relevance score of specific terms in the query.
+ * - `MultiMatch`: Searches across multiple fields for the query terms.
+ */
+export declare enum FullTextQueryType {
+    Match = "match",
+    MatchPhrase = "match_phrase",
+    Boost = "boost",
+    MultiMatch = "multi_match"
+}
+/**
+ * Represents a full-text query interface.
+ * This interface defines the structure and behavior for full-text queries,
+ * including methods to retrieve the query type and convert the query to a dictionary format.
+ */
+export interface FullTextQuery {
+    queryType(): FullTextQueryType;
+    toDict(): Record<string, unknown>;
+}
+export declare class MatchQuery implements FullTextQuery {
+    private query;
+    private column;
+    private boost;
+    private fuzziness;
+    private maxExpansions;
+    /**
+     * 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`.
+     */
+    constructor(query: string, column: string, boost?: number, fuzziness?: number, maxExpansions?: number);
+    queryType(): FullTextQueryType;
+    toDict(): Record<string, unknown>;
+}
+export declare class PhraseQuery implements FullTextQuery {
+    private query;
+    private column;
+    /**
+     * Creates an instance of `PhraseQuery`.
+     *
+     * @param query - The phrase to search for in the specified column.
+     * @param column - The name of the column to search within.
+     */
+    constructor(query: string, column: string);
+    queryType(): FullTextQueryType;
+    toDict(): Record<string, unknown>;
+}
+export declare class BoostQuery implements FullTextQuery {
+    private positive;
+    private negative;
+    private negativeBoost;
+    /**
+     * Creates an instance of BoostQuery.
+     *
+     * @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.
+     */
+    constructor(positive: FullTextQuery, negative: FullTextQuery, negativeBoost: number);
+    queryType(): FullTextQueryType;
+    toDict(): Record<string, unknown>;
+}
+export declare class MultiMatchQuery implements FullTextQuery {
+    private query;
+    private columns;
+    private boosts;
+    /**
+     * 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.
+     */
+    constructor(query: string, columns: string[], boosts?: number[]);
+    queryType(): FullTextQueryType;
+    toDict(): Record<string, unknown>;
 }

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.Query = exports.VectorQuery = exports.QueryBase = exports.RecordBatchIterator = void 0;
+exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.FullTextQueryType = exports.Query = exports.VectorQuery = exports.QueryBase = exports.RecordBatchIterator = void 0;
 const arrow_1 = require("./arrow");
 class RecordBatchIterator {
     promisedInner;
@@ -109,7 +109,19 @@ class QueryBase {
                 columns = options.columns;
             }
         }
-        this.doCall((inner) => inner.fullTextSearch(query, columns));
+        this.doCall((inner) => {
+            if (typeof query === "string") {
+                inner.fullTextSearch({
+                    query: query,
+                    columns: columns,
+                });
+            }
+            else {
+                // If query is a FullTextQuery object, convert it to a dict
+                const queryObj = query.toDict();
+                inner.fullTextSearch(queryObj);
+            }
+        });
         return this;
     }
     /**
@@ -278,6 +290,43 @@ class QueryBase {
             return this.inner.explainPlan(verbose);
         }
     }
+    /**
+     * Executes the query and returns the physical query plan annotated with runtime metrics.
+     *
+     * This is useful for debugging and performance analysis, as it shows how the query was executed
+     * and includes metrics such as elapsed time, rows processed, and I/O statistics.
+     *
+     * @example
+     * import * as lancedb from "@lancedb/lancedb"
+     *
+     * const db = await lancedb.connect("./.lancedb");
+     * const table = await db.createTable("my_table", [
+     *   { vector: [1.1, 0.9], id: "1" },
+     * ]);
+     *
+     * const plan = await table.query().nearestTo([0.5, 0.2]).analyzePlan();
+     *
+     * Example output (with runtime metrics inlined):
+     * AnalyzeExec verbose=true, metrics=[]
+     *  ProjectionExec: expr=[id@3 as id, vector@0 as vector, _distance@2 as _distance], metrics=[output_rows=1, elapsed_compute=3.292µs]
+     *   Take: columns="vector, _rowid, _distance, (id)", metrics=[output_rows=1, elapsed_compute=66.001µs, batches_processed=1, bytes_read=8, iops=1, requests=1]
+     *    CoalesceBatchesExec: target_batch_size=1024, metrics=[output_rows=1, elapsed_compute=3.333µs]
+     *     GlobalLimitExec: skip=0, fetch=10, metrics=[output_rows=1, elapsed_compute=167ns]
+     *      FilterExec: _distance@2 IS NOT NULL, metrics=[output_rows=1, elapsed_compute=8.542µs]
+     *       SortExec: TopK(fetch=10), expr=[_distance@2 ASC NULLS LAST], metrics=[output_rows=1, elapsed_compute=63.25µs, row_replacements=1]
+     *        KNNVectorDistance: metric=l2, metrics=[output_rows=1, elapsed_compute=114.333µs, output_batches=1]
+     *         LanceScan: uri=/path/to/data, projection=[vector], row_id=true, row_addr=false, ordered=false, metrics=[output_rows=1, elapsed_compute=103.626µs, bytes_read=549, iops=2, requests=2]
+     *
+     * @returns A query execution plan with runtime metrics for each step.
+     */
+    async analyzePlan() {
+        if (this.inner instanceof Promise) {
+            return this.inner.then((inner) => inner.analyzePlan());
+        }
+        else {
+            return this.inner.analyzePlan();
+        }
+    }
 }
 exports.QueryBase = QueryBase;
 /**
@@ -583,8 +632,163 @@ class Query extends QueryBase {
         }
     }
     nearestToText(query, columns) {
-        this.doCall((inner) => inner.fullTextSearch(query, columns));
+        this.doCall((inner) => {
+            if (typeof query === "string") {
+                inner.fullTextSearch({
+                    query: query,
+                    columns: columns,
+                });
+            }
+            else {
+                const queryObj = query.toDict();
+                inner.fullTextSearch(queryObj);
+            }
+        });
         return this;
     }
 }
 exports.Query = Query;
+/**
+ * Enum representing the types of full-text queries supported.
+ *
+ * - `Match`: Performs a full-text search for terms in the query string.
+ * - `MatchPhrase`: Searches for an exact phrase match in the text.
+ * - `Boost`: Boosts the relevance score of specific terms in the query.
+ * - `MultiMatch`: Searches across multiple fields for the query terms.
+ */
+var FullTextQueryType;
+(function (FullTextQueryType) {
+    FullTextQueryType["Match"] = "match";
+    FullTextQueryType["MatchPhrase"] = "match_phrase";
+    FullTextQueryType["Boost"] = "boost";
+    FullTextQueryType["MultiMatch"] = "multi_match";
+})(FullTextQueryType || (exports.FullTextQueryType = FullTextQueryType = {}));
+class MatchQuery {
+    query;
+    column;
+    boost;
+    fuzziness;
+    maxExpansions;
+    /**
+     * 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`.
+     */
+    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;
+    }
+    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;
+    /**
+     * Creates an instance of `PhraseQuery`.
+     *
+     * @param query - The phrase to search for in the specified column.
+     * @param column - The name of the column to search within.
+     */
+    constructor(query, column) {
+        this.query = query;
+        this.column = column;
+    }
+    queryType() {
+        return FullTextQueryType.MatchPhrase;
+    }
+    toDict() {
+        return {
+            [this.queryType()]: {
+                [this.column]: this.query,
+            },
+        };
+    }
+}
+exports.PhraseQuery = PhraseQuery;
+class BoostQuery {
+    positive;
+    negative;
+    negativeBoost;
+    /**
+     * Creates an instance of BoostQuery.
+     *
+     * @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.
+     */
+    constructor(positive, negative, negativeBoost) {
+        this.positive = positive;
+        this.negative = negative;
+        this.negativeBoost = 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;
+    /**
+     * 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.
+     */
+    constructor(query, columns, boosts = columns.map(() => 1.0)) {
+        this.query = query;
+        this.columns = columns;
+        this.boosts = boosts;
+    }
+    queryType() {
+        return FullTextQueryType.MultiMatch;
+    }
+    toDict() {
+        return {
+            [this.queryType()]: {
+                query: this.query,
+                columns: this.columns,
+                boost: this.boosts,
+            },
+        };
+    }
+}
+exports.MultiMatchQuery = MultiMatchQuery;

package/package.json

@@ -11,7 +11,7 @@
     "ann"
   ],
   "private": false,
-  "version": "0.18.3-beta.0",
+  "version": "0.19.0-beta.3",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -29,6 +29,7 @@
         "aarch64-apple-darwin",
         "x86_64-unknown-linux-gnu",
         "aarch64-unknown-linux-gnu",
+        "x86_64-unknown-linux-musl",
         "aarch64-unknown-linux-musl",
         "x86_64-pc-windows-msvc",
         "aarch64-pc-windows-msvc"
@@ -99,13 +100,14 @@
     "reflect-metadata": "^0.2.2"
   },
   "optionalDependencies": {
-    "@lancedb/lancedb-darwin-x64": "0.18.3-beta.0",
-    "@lancedb/lancedb-darwin-arm64": "0.18.3-beta.0",
-    "@lancedb/lancedb-linux-x64-gnu": "0.18.3-beta.0",
-    "@lancedb/lancedb-linux-arm64-gnu": "0.18.3-beta.0",
-    "@lancedb/lancedb-linux-arm64-musl": "0.18.3-beta.0",
-    "@lancedb/lancedb-win32-x64-msvc": "0.18.3-beta.0",
-    "@lancedb/lancedb-win32-arm64-msvc": "0.18.3-beta.0"
+    "@lancedb/lancedb-darwin-x64": "0.19.0-beta.3",
+    "@lancedb/lancedb-darwin-arm64": "0.19.0-beta.3",
+    "@lancedb/lancedb-linux-x64-gnu": "0.19.0-beta.3",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.19.0-beta.3",
+    "@lancedb/lancedb-linux-x64-musl": "0.19.0-beta.3",
+    "@lancedb/lancedb-linux-arm64-musl": "0.19.0-beta.3",
+    "@lancedb/lancedb-win32-x64-msvc": "0.19.0-beta.3",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.19.0-beta.3"
   },
   "peerDependencies": {
     "apache-arrow": ">=15.0.0 <=18.1.0"