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

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.
    *
@@ -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
@@ -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

@@ -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

package/dist/query.js

@@ -278,6 +278,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;
 /**

package/package.json

@@ -11,7 +11,7 @@
     "ann"
   ],
   "private": false,
-  "version": "0.18.3-beta.0",
+  "version": "0.19.0-beta.0",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -99,13 +99,13 @@
     "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.0",
+    "@lancedb/lancedb-darwin-arm64": "0.19.0-beta.0",
+    "@lancedb/lancedb-linux-x64-gnu": "0.19.0-beta.0",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.19.0-beta.0",
+    "@lancedb/lancedb-linux-arm64-musl": "0.19.0-beta.0",
+    "@lancedb/lancedb-win32-x64-msvc": "0.19.0-beta.0",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.19.0-beta.0"
   },
   "peerDependencies": {
     "apache-arrow": ">=15.0.0 <=18.1.0"