feat: return version for all write operations (#2368)

return version info for all write operations (add, update, merge_insert
and column modification operations)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Table modification operations (add, update, delete, merge,
add/alter/drop columns) now return detailed result objects including
version numbers and operation statistics.
- Result objects provide clearer feedback such as rows affected and new
table version after each operation.

- **Documentation**
- Updated documentation to describe new result objects and their fields
for all relevant table operations.
- Added documentation for new result interfaces and updated method
return types in Node.js and Python APIs.

- **Tests**
- Enhanced test coverage to assert correctness of returned versioning
and operation metadata after table modifications.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

nodejs/__test__/table.test.ts

@@ -34,6 +34,7 @@ import {
 } from "../lancedb/embedding";
 import { Index } from "../lancedb/indices";
 import { instanceOfFullTextQuery } from "../lancedb/query";
+import exp = require("constants");
 
 describe.each([arrow15, arrow16, arrow17, arrow18])(
   "Given a table",
@@ -95,7 +96,9 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
     });
 
     it("should overwrite data if asked", async () => {
-      await table.add([{ id: 1 }, { id: 2 }]);
+      const addRes = await table.add([{ id: 1 }, { id: 2 }]);
+      expect(addRes).toHaveProperty("version");
+      expect(addRes.version).toBe(2);
       await table.add([{ id: 1 }], { mode: "overwrite" });
       await expect(table.countRows()).resolves.toBe(1);
     });
@@ -111,7 +114,11 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
       await table.add([{ id: 1 }]);
       expect(await table.countRows("id == 1")).toBe(1);
       expect(await table.countRows("id == 7")).toBe(0);
-      await table.update({ id: "7" });
+      const updateRes = await table.update({ id: "7" });
+      expect(updateRes).toHaveProperty("version");
+      expect(updateRes.version).toBe(3);
+      expect(updateRes).toHaveProperty("rowsUpdated");
+      expect(updateRes.rowsUpdated).toBe(1);
       expect(await table.countRows("id == 1")).toBe(0);
       expect(await table.countRows("id == 7")).toBe(1);
       await table.add([{ id: 2 }]);
@@ -338,15 +345,16 @@ describe("merge insert", () => {
       { a: 3, b: "y" },
       { a: 4, b: "z" },
     ];
-    const stats = await table
+    const mergeInsertRes = await table
       .mergeInsert("a")
       .whenMatchedUpdateAll()
       .whenNotMatchedInsertAll()
       .execute(newData);
-
-    expect(stats.numInsertedRows).toBe(1n);
-    expect(stats.numUpdatedRows).toBe(2n);
-    expect(stats.numDeletedRows).toBe(0n);
+    expect(mergeInsertRes).toHaveProperty("version");
+    expect(mergeInsertRes.version).toBe(2);
+    expect(mergeInsertRes.numInsertedRows).toBe(1);
+    expect(mergeInsertRes.numUpdatedRows).toBe(2);
+    expect(mergeInsertRes.numDeletedRows).toBe(0);
 
     const expected = [
       { a: 1, b: "a" },
@@ -365,10 +373,12 @@ describe("merge insert", () => {
       { a: 3, b: "y" },
       { a: 4, b: "z" },
     ];
-    await table
+    const mergeInsertRes = await table
       .mergeInsert("a")
       .whenMatchedUpdateAll({ where: "target.b = 'b'" })
       .execute(newData);
+    expect(mergeInsertRes).toHaveProperty("version");
+    expect(mergeInsertRes.version).toBe(2);
 
     const expected = [
       { a: 1, b: "a" },
@@ -1028,15 +1038,19 @@ describe("schema evolution", function () {
       { id: 1n, vector: [0.1, 0.2] },
     ]);
     // Can create a non-nullable column only through addColumns at the moment.
-    await table.addColumns([
+    const addColumnsRes = await table.addColumns([
       { name: "price", valueSql: "cast(10.0 as double)" },
     ]);
+    expect(addColumnsRes).toHaveProperty("version");
+    expect(addColumnsRes.version).toBe(2);
     expect(await table.schema()).toEqual(schema);
 
-    await table.alterColumns([
+    const alterColumnsRes = await table.alterColumns([
       { path: "id", rename: "new_id" },
       { path: "price", nullable: true },
     ]);
+    expect(alterColumnsRes).toHaveProperty("version");
+    expect(alterColumnsRes.version).toBe(3);
 
     const expectedSchema = new Schema([
       new Field("new_id", new Int64(), true),
@@ -1154,7 +1168,9 @@ describe("schema evolution", function () {
     const table = await con.createTable("vectors", [
       { id: 1n, vector: [0.1, 0.2] },
     ]);
-    await table.dropColumns(["vector"]);
+    const dropColumnsRes = await table.dropColumns(["vector"]);
+    expect(dropColumnsRes).toHaveProperty("version");
+    expect(dropColumnsRes.version).toBe(2);
 
     const expectedSchema = new Schema([new Field("id", new Int64(), true)]);
     expect(await table.schema()).toEqual(expectedSchema);

nodejs/lancedb/index.ts

@@ -28,7 +28,13 @@ export {
   FragmentSummaryStats,
   Tags,
   TagContents,
-  MergeStats,
+  MergeResult,
+  AddResult,
+  AddColumnsResult,
+  AlterColumnsResult,
+  DeleteResult,
+  DropColumnsResult,
+  UpdateResult,
 } from "./native.js";
 
 export {

nodejs/lancedb/merge.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 import { Data, Schema, fromDataToBuffer } from "./arrow";
-import { MergeStats, NativeMergeInsertBuilder } from "./native";
+import { MergeResult, NativeMergeInsertBuilder } from "./native";
 
 /** A builder used to create and run a merge insert operation */
 export class MergeInsertBuilder {
@@ -73,9 +73,9 @@ export class MergeInsertBuilder {
   /**
    * Executes the merge insert operation
    *
-   * @returns Statistics about the merge operation: counts of inserted, updated, and deleted rows
+   * @returns {Promise<MergeResult>} the merge result
    */
-  async execute(data: Data): Promise<MergeStats> {
+  async execute(data: Data): Promise<MergeResult> {
     let schema: Schema;
     if (this.#schema instanceof Promise) {
       schema = await this.#schema;

nodejs/lancedb/table.ts

@@ -16,12 +16,18 @@ import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
 import { IndexOptions } from "./indices";
 import { MergeInsertBuilder } from "./merge";
 import {
+  AddColumnsResult,
   AddColumnsSql,
+  AddResult,
+  AlterColumnsResult,
+  DeleteResult,
+  DropColumnsResult,
   IndexConfig,
   IndexStatistics,
   OptimizeStats,
   TableStatistics,
   Tags,
+  UpdateResult,
   Table as _NativeTable,
 } from "./native";
 import {
@@ -126,12 +132,19 @@ export abstract class Table {
   /**
    * Insert records into this Table.
    * @param {Data} data Records to be inserted into the Table
+   * @returns {Promise<AddResult>} A promise that resolves to an object
+   * containing the new version number of the table
    */
-  abstract add(data: Data, options?: Partial<AddDataOptions>): Promise<void>;
+  abstract add(
+    data: Data,
+    options?: Partial<AddDataOptions>,
+  ): Promise<AddResult>;
   /**
    * Update existing records in the Table
    * @param opts.values The values to update. The keys are the column names and the values
    * are the values to set.
+   * @returns {Promise<UpdateResult>} A promise that resolves to an object containing
+   * the number of rows updated and the new version number
    * @example
    * ```ts
    * table.update({where:"x = 2", values:{"vector": [10, 10]}})
@@ -141,11 +154,13 @@ export abstract class Table {
     opts: {
       values: Map<string, IntoSql> | Record<string, IntoSql>;
     } & Partial<UpdateOptions>,
-  ): Promise<void>;
+  ): Promise<UpdateResult>;
   /**
    * Update existing records in the Table
    * @param opts.valuesSql The values to update. The keys are the column names and the values
    * are the values to set. The values are SQL expressions.
+   * @returns {Promise<UpdateResult>} A promise that resolves to an object containing
+   * the number of rows updated and the new version number
    * @example
    * ```ts
    * table.update({where:"x = 2", valuesSql:{"x": "x + 1"}})
@@ -155,7 +170,7 @@ export abstract class Table {
     opts: {
       valuesSql: Map<string, string> | Record<string, string>;
     } & Partial<UpdateOptions>,
-  ): Promise<void>;
+  ): Promise<UpdateResult>;
   /**
    * Update existing records in the Table
    *
@@ -173,6 +188,8 @@ export abstract class Table {
    * repeatedly calilng this method.
    * @param {Map<string, string> | Record<string, string>} updates - the
    * columns to update
+   * @returns {Promise<UpdateResult>} A promise that resolves to an object
+   * containing the number of rows updated and the new version number
    *
    * Keys in the map should specify the name of the column to update.
    * Values in the map provide the new value of the column.  These can
@@ -184,12 +201,16 @@ export abstract class Table {
   abstract update(
     updates: Map<string, string> | Record<string, string>,
     options?: Partial<UpdateOptions>,
-  ): Promise<void>;
+  ): Promise<UpdateResult>;
 
   /** Count the total number of rows in the dataset. */
   abstract countRows(filter?: string): Promise<number>;
-  /** Delete the rows that satisfy the predicate. */
-  abstract delete(predicate: string): Promise<void>;
+  /**
+   * Delete the rows that satisfy the predicate.
+   * @returns {Promise<DeleteResult>} A promise that resolves to an object
+   * containing the new version number of the table
+   */
+  abstract delete(predicate: string): Promise<DeleteResult>;
   /**
    * Create an index to speed up queries.
    *
@@ -343,15 +364,23 @@ export abstract class Table {
    * the SQL expression to use to calculate the value of the new column. These
    * expressions will be evaluated for each row in the table, and can
    * reference existing columns in the table.
+   * @returns {Promise<AddColumnsResult>} A promise that resolves to an object
+   * containing the new version number of the table after adding the columns.
    */
-  abstract addColumns(newColumnTransforms: AddColumnsSql[]): Promise<void>;
+  abstract addColumns(
+    newColumnTransforms: AddColumnsSql[],
+  ): Promise<AddColumnsResult>;
 
   /**
    * Alter the name or nullability of columns.
    * @param {ColumnAlteration[]} columnAlterations One or more alterations to
    * apply to columns.
+   * @returns {Promise<AlterColumnsResult>} A promise that resolves to an object
+   * containing the new version number of the table after altering the columns.
    */
-  abstract alterColumns(columnAlterations: ColumnAlteration[]): Promise<void>;
+  abstract alterColumns(
+    columnAlterations: ColumnAlteration[],
+  ): Promise<AlterColumnsResult>;
   /**
    * Drop one or more columns from the dataset
    *
@@ -362,8 +391,10 @@ export abstract class Table {
    * @param {string[]} columnNames The names of the columns to drop. These can
    * be nested column references (e.g. "a.b.c") or top-level column names
    * (e.g. "a").
+   * @returns {Promise<DropColumnsResult>} A promise that resolves to an object
+   * containing the new version number of the table after dropping the columns.
    */
-  abstract dropColumns(columnNames: string[]): Promise<void>;
+  abstract dropColumns(columnNames: string[]): Promise<DropColumnsResult>;
   /** Retrieve the version of the table */
 
   abstract version(): Promise<number>;
@@ -529,12 +560,12 @@ export class LocalTable extends Table {
     return tbl.schema;
   }
 
-  async add(data: Data, options?: Partial<AddDataOptions>): Promise<void> {
+  async add(data: Data, options?: Partial<AddDataOptions>): Promise<AddResult> {
     const mode = options?.mode ?? "append";
     const schema = await this.schema();
 
     const buffer = await fromDataToBuffer(data, undefined, schema);
-    await this.inner.add(buffer, mode);
+    return await this.inner.add(buffer, mode);
   }
 
   async update(
@@ -547,7 +578,7 @@ export class LocalTable extends Table {
           valuesSql: Map<string, string> | Record<string, string>;
         } & Partial<UpdateOptions>),
     options?: Partial<UpdateOptions>,
-  ) {
+  ): Promise<UpdateResult> {
     const isValues =
       "values" in optsOrUpdates && typeof optsOrUpdates.values !== "string";
     const isValuesSql =
@@ -594,15 +625,15 @@ export class LocalTable extends Table {
         columns = Object.entries(optsOrUpdates as Record<string, string>);
         predicate = options?.where;
     }
-    await this.inner.update(predicate, columns);
+    return await this.inner.update(predicate, columns);
   }
 
   async countRows(filter?: string): Promise<number> {
     return await this.inner.countRows(filter);
   }
 
-  async delete(predicate: string): Promise<void> {
-    await this.inner.delete(predicate);
+  async delete(predicate: string): Promise<DeleteResult> {
+    return await this.inner.delete(predicate);
   }
 
   async createIndex(column: string, options?: Partial<IndexOptions>) {
@@ -690,11 +721,15 @@ export class LocalTable extends Table {
 
   // TODO: Support BatchUDF
 
-  async addColumns(newColumnTransforms: AddColumnsSql[]): Promise<void> {
-    await this.inner.addColumns(newColumnTransforms);
+  async addColumns(
+    newColumnTransforms: AddColumnsSql[],
+  ): Promise<AddColumnsResult> {
+    return await this.inner.addColumns(newColumnTransforms);
   }
 
-  async alterColumns(columnAlterations: ColumnAlteration[]): Promise<void> {
+  async alterColumns(
+    columnAlterations: ColumnAlteration[],
+  ): Promise<AlterColumnsResult> {
     const processedAlterations = columnAlterations.map((alteration) => {
       if (typeof alteration.dataType === "string") {
         return {
@@ -715,11 +750,11 @@ export class LocalTable extends Table {
       }
     });
 
-    await this.inner.alterColumns(processedAlterations);
+    return await this.inner.alterColumns(processedAlterations);
   }
 
-  async dropColumns(columnNames: string[]): Promise<void> {
-    await this.inner.dropColumns(columnNames);
+  async dropColumns(columnNames: string[]): Promise<DropColumnsResult> {
+    return await this.inner.dropColumns(columnNames);
   }
 
   async version(): Promise<number> {

nodejs/src/merge.rs

@@ -5,7 +5,7 @@ use lancedb::{arrow::IntoArrow, ipc::ipc_file_to_batches, table::merge::MergeIns
 use napi::bindgen_prelude::*;
 use napi_derive::napi;
 
-use crate::error::convert_error;
+use crate::{error::convert_error, table::MergeResult};
 
 #[napi]
 #[derive(Clone)]
@@ -37,7 +37,7 @@ impl NativeMergeInsertBuilder {
     }
 
     #[napi(catch_unwind)]
-    pub async fn execute(&self, buf: Buffer) -> napi::Result<MergeStats> {
+    pub async fn execute(&self, buf: Buffer) -> napi::Result<MergeResult> {
         let data = ipc_file_to_batches(buf.to_vec())
             .and_then(IntoArrow::into_arrow)
             .map_err(|e| {
@@ -46,14 +46,13 @@ impl NativeMergeInsertBuilder {
 
         let this = self.clone();
 
-        let stats = this.inner.execute(data).await.map_err(|e| {
+        let res = this.inner.execute(data).await.map_err(|e| {
             napi::Error::from_reason(format!(
                 "Failed to execute merge insert: {}",
                 convert_error(&e)
             ))
         })?;
-
-        Ok(stats.into())
+        Ok(res.into())
     }
 }
 
@@ -62,20 +61,3 @@ impl From<MergeInsertBuilder> for NativeMergeInsertBuilder {
         Self { inner }
     }
 }
-
-#[napi(object)]
-pub struct MergeStats {
-    pub num_inserted_rows: BigInt,
-    pub num_updated_rows: BigInt,
-    pub num_deleted_rows: BigInt,
-}
-
-impl From<lancedb::table::MergeStats> for MergeStats {
-    fn from(stats: lancedb::table::MergeStats) -> Self {
-        Self {
-            num_inserted_rows: stats.num_inserted_rows.into(),
-            num_updated_rows: stats.num_updated_rows.into(),
-            num_deleted_rows: stats.num_deleted_rows.into(),
-        }
-    }
-}

nodejs/src/table.rs

@@ -75,7 +75,7 @@ impl Table {
     }
 
     #[napi(catch_unwind)]
-    pub async fn add(&self, buf: Buffer, mode: String) -> napi::Result<()> {
+    pub async fn add(&self, buf: Buffer, mode: String) -> napi::Result<AddResult> {
         let batches = ipc_file_to_batches(buf.to_vec())
             .map_err(|e| napi::Error::from_reason(format!("Failed to read IPC file: {}", e)))?;
         let mut op = self.inner_ref()?.add(batches);
@@ -88,7 +88,8 @@ impl Table {
             return Err(napi::Error::from_reason(format!("Invalid mode: {}", mode)));
         };
 
-        op.execute().await.default_error()
+        let res = op.execute().await.default_error()?;
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
@@ -101,8 +102,9 @@ impl Table {
     }
 
     #[napi(catch_unwind)]
-    pub async fn delete(&self, predicate: String) -> napi::Result<()> {
-        self.inner_ref()?.delete(&predicate).await.default_error()
+    pub async fn delete(&self, predicate: String) -> napi::Result<DeleteResult> {
+        let res = self.inner_ref()?.delete(&predicate).await.default_error()?;
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
@@ -168,7 +170,7 @@ impl Table {
         &self,
         only_if: Option<String>,
         columns: Vec<(String, String)>,
-    ) -> napi::Result<u64> {
+    ) -> napi::Result<UpdateResult> {
         let mut op = self.inner_ref()?.update();
         if let Some(only_if) = only_if {
             op = op.only_if(only_if);
@@ -176,7 +178,8 @@ impl Table {
         for (column_name, value) in columns {
             op = op.column(column_name, value);
         }
-        op.execute().await.default_error()
+        let res = op.execute().await.default_error()?;
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
@@ -190,21 +193,28 @@ impl Table {
     }
 
     #[napi(catch_unwind)]
-    pub async fn add_columns(&self, transforms: Vec<AddColumnsSql>) -> napi::Result<()> {
+    pub async fn add_columns(
+        &self,
+        transforms: Vec<AddColumnsSql>,
+    ) -> napi::Result<AddColumnsResult> {
         let transforms = transforms
             .into_iter()
             .map(|sql| (sql.name, sql.value_sql))
             .collect::<Vec<_>>();
         let transforms = NewColumnTransform::SqlExpressions(transforms);
-        self.inner_ref()?
+        let res = self
+            .inner_ref()?
             .add_columns(transforms, None)
             .await
             .default_error()?;
-        Ok(())
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
-    pub async fn alter_columns(&self, alterations: Vec<ColumnAlteration>) -> napi::Result<()> {
+    pub async fn alter_columns(
+        &self,
+        alterations: Vec<ColumnAlteration>,
+    ) -> napi::Result<AlterColumnsResult> {
         for alteration in &alterations {
             if alteration.rename.is_none()
                 && alteration.nullable.is_none()
@@ -221,21 +231,23 @@ impl Table {
             .collect::<std::result::Result<Vec<_>, String>>()
             .map_err(napi::Error::from_reason)?;
 
-        self.inner_ref()?
+        let res = self
+            .inner_ref()?
             .alter_columns(&alterations)
             .await
             .default_error()?;
-        Ok(())
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
-    pub async fn drop_columns(&self, columns: Vec<String>) -> napi::Result<()> {
+    pub async fn drop_columns(&self, columns: Vec<String>) -> napi::Result<DropColumnsResult> {
         let col_refs = columns.iter().map(String::as_str).collect::<Vec<_>>();
-        self.inner_ref()?
+        let res = self
+            .inner_ref()?
             .drop_columns(&col_refs)
             .await
             .default_error()?;
-        Ok(())
+        Ok(res.into())
     }
 
     #[napi(catch_unwind)]
@@ -642,6 +654,105 @@ pub struct Version {
     pub metadata: HashMap<String, String>,
 }
 
+#[napi(object)]
+pub struct UpdateResult {
+    pub rows_updated: i64,
+    pub version: i64,
+}
+
+impl From<lancedb::table::UpdateResult> for UpdateResult {
+    fn from(value: lancedb::table::UpdateResult) -> Self {
+        Self {
+            rows_updated: value.rows_updated as i64,
+            version: value.version as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct AddResult {
+    pub version: i64,
+}
+
+impl From<lancedb::table::AddResult> for AddResult {
+    fn from(value: lancedb::table::AddResult) -> Self {
+        Self {
+            version: value.version as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct DeleteResult {
+    pub version: i64,
+}
+
+impl From<lancedb::table::DeleteResult> for DeleteResult {
+    fn from(value: lancedb::table::DeleteResult) -> Self {
+        Self {
+            version: value.version as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct MergeResult {
+    pub version: i64,
+    pub num_inserted_rows: i64,
+    pub num_updated_rows: i64,
+    pub num_deleted_rows: i64,
+}
+
+impl From<lancedb::table::MergeResult> for MergeResult {
+    fn from(value: lancedb::table::MergeResult) -> Self {
+        Self {
+            version: value.version as i64,
+            num_inserted_rows: value.num_inserted_rows as i64,
+            num_updated_rows: value.num_updated_rows as i64,
+            num_deleted_rows: value.num_deleted_rows as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct AddColumnsResult {
+    pub version: i64,
+}
+
+impl From<lancedb::table::AddColumnsResult> for AddColumnsResult {
+    fn from(value: lancedb::table::AddColumnsResult) -> Self {
+        Self {
+            version: value.version as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct AlterColumnsResult {
+    pub version: i64,
+}
+
+impl From<lancedb::table::AlterColumnsResult> for AlterColumnsResult {
+    fn from(value: lancedb::table::AlterColumnsResult) -> Self {
+        Self {
+            version: value.version as i64,
+        }
+    }
+}
+
+#[napi(object)]
+pub struct DropColumnsResult {
+    pub version: i64,
+}
+
+impl From<lancedb::table::DropColumnsResult> for DropColumnsResult {
+    fn from(value: lancedb::table::DropColumnsResult) -> Self {
+        Self {
+            version: value.version as i64,
+        }
+    }
+}
+
 #[napi]
 pub struct TagContents {
     pub version: i64,