feat: add analyze_plan api (#2280)

add analyze plan api to allow executing the queries and see runtime
metrics.
Which help identify the query IO overhead and help identify query
slowness

nodejs/__test__/table.test.ts

@@ -633,6 +633,23 @@ describe("When creating an index", () => {
     expect(plan2).not.toMatch("LanceScan");
   });
 
+  it("should be able to run analyze plan", async () => {
+    await tbl.createIndex("vec");
+    await tbl.add([
+      {
+        id: 300,
+        vec: Array(32)
+          .fill(1)
+          .map(() => Math.random()),
+        tags: [],
+      },
+    ]);
+
+    const plan = await tbl.query().nearestTo(queryVec).analyzePlan();
+    expect(plan).toMatch("AnalyzeExec");
+    expect(plan).toMatch("metrics=");
+  });
+
   it("should be able to query with row id", async () => {
     const results = await tbl
       .query()
@@ -1346,6 +1363,30 @@ describe("when calling explainPlan", () => {
   });
 });
 
+describe("when calling analyzePlan", () => {
+  let tmpDir: tmp.DirResult;
+  let table: Table;
+  let queryVec: number[];
+  beforeEach(async () => {
+    tmpDir = tmp.dirSync({ unsafeCleanup: true });
+    const con = await connect(tmpDir.name);
+    table = await con.createTable("vectors", [{ id: 1, vector: [1.1, 0.9] }]);
+  });
+
+  afterEach(() => {
+    tmpDir.removeCallback();
+  });
+
+  it("retrieves runtime metrics", async () => {
+    queryVec = Array(2)
+      .fill(1)
+      .map(() => Math.random());
+    const plan = await table.query().nearestTo(queryVec).analyzePlan();
+    console.log("Query Plan:\n", plan); // <--- Print the plan
+    expect(plan).toMatch("AnalyzeExec");
+  });
+});
+
 describe("column name options", () => {
   let tmpDir: tmp.DirResult;
   let table: Table;

nodejs/lancedb/query.ts

@@ -348,6 +348,43 @@ export class QueryBase<NativeQueryType extends NativeQuery | NativeVectorQuery>
       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(): Promise<string> {
+    if (this.inner instanceof Promise) {
+      return this.inner.then((inner) => inner.analyzePlan());
+    } else {
+      return this.inner.analyzePlan();
+    }
+  }
 }
 
 /**

nodejs/src/query.rs

@@ -114,6 +114,16 @@ impl Query {
             ))
         })
     }
+
+    #[napi(catch_unwind)]
+    pub async fn analyze_plan(&self) -> napi::Result<String> {
+        self.inner.analyze_plan().await.map_err(|e| {
+            napi::Error::from_reason(format!(
+                "Failed to execute analyze plan: {}",
+                convert_error(&e)
+            ))
+        })
+    }
 }
 
 #[napi]
@@ -259,4 +269,14 @@ impl VectorQuery {
             ))
         })
     }
+
+    #[napi(catch_unwind)]
+    pub async fn analyze_plan(&self) -> napi::Result<String> {
+        self.inner.analyze_plan().await.map_err(|e| {
+            napi::Error::from_reason(format!(
+                "Failed to execute analyze plan: {}",
+                convert_error(&e)
+            ))
+        })
+    }
 }