[Node] Create Table with WriteMode (#246)

Support `createTable(name, data, mode?)`  to be consistent with Python.

Closes #242

node/src/index.ts

@@ -37,7 +37,7 @@ export async function connect (uri: string): Promise<Connection> {
 }
 
 /**
- * A LanceDB connection that allows you to open tables and create new ones.
+ * A LanceDB Connection that allows you to open tables and create new ones.
  *
  * Connection could be local against filesystem or remote against a server.
  */
@@ -56,11 +56,14 @@ export interface Connection {
   /**
    * Creates a new Table and initialize it with new data.
    *
-   * @param name The name of the table.
-   * @param data Non-empty Array of Records to be inserted into the Table
+   * @param {string} name - The name of the table.
+   * @param data - Non-empty Array of Records to be inserted into the Table
    */
 
-  createTable: ((name: string, data: Array<Record<string, unknown>>) => Promise<Table>) & (<T>(name: string, data: Array<Record<string, unknown>>, embeddings: EmbeddingFunction<T>) => Promise<Table<T>>) & (<T>(name: string, data: Array<Record<string, unknown>>, embeddings?: EmbeddingFunction<T>) => Promise<Table<T>>)
+  createTable: ((name: string, data: Array<Record<string, unknown>>, mode?: WriteMode) => Promise<Table>)
+  & ((name: string, data: Array<Record<string, unknown>>, mode: WriteMode) => Promise<Table>)
+  & (<T>(name: string, data: Array<Record<string, unknown>>, mode: WriteMode, embeddings: EmbeddingFunction<T>) => Promise<Table<T>>)
+  & (<T>(name: string, data: Array<Record<string, unknown>>, mode: WriteMode, embeddings?: EmbeddingFunction<T>) => Promise<Table<T>>)
 
   createTableArrow: (name: string, table: ArrowTable) => Promise<Table>
 
@@ -72,7 +75,7 @@ export interface Connection {
 }
 
 /**
- * A LanceDB table that allows you to search and update a table.
+ * A LanceDB Table is the collection of Records. Each Record has one or more vector fields.
  */
 export interface Table<T = number[]> {
   name: string
@@ -169,19 +172,25 @@ export class LocalConnection implements Connection {
    *
    * @param name The name of the table.
    * @param data Non-empty Array of Records to be inserted into the Table
+   * @param mode The write mode to use when creating the table.
    */
+  async createTable (name: string, data: Array<Record<string, unknown>>, mode?: WriteMode): Promise<Table>
+  async createTable (name: string, data: Array<Record<string, unknown>>, mode: WriteMode): Promise<Table>
 
-  async createTable (name: string, data: Array<Record<string, unknown>>): Promise<Table>
   /**
    * Creates a new Table and initialize it with new data.
    *
    * @param name The name of the table.
    * @param data Non-empty Array of Records to be inserted into the Table
+   * @param mode The write mode to use when creating the table.
    * @param embeddings An embedding function to use on this Table
    */
-  async createTable<T> (name: string, data: Array<Record<string, unknown>>, embeddings: EmbeddingFunction<T>): Promise<Table<T>>
-  async createTable<T> (name: string, data: Array<Record<string, unknown>>, embeddings?: EmbeddingFunction<T>): Promise<Table<T>> {
-    const tbl = await tableCreate.call(this._db, name, await fromRecordsToBuffer(data, embeddings))
+  async createTable<T> (name: string, data: Array<Record<string, unknown>>, mode: WriteMode, embeddings: EmbeddingFunction<T>): Promise<Table<T>>
+  async createTable<T> (name: string, data: Array<Record<string, unknown>>, mode: WriteMode, embeddings?: EmbeddingFunction<T>): Promise<Table<T>> {
+    if (mode === undefined) {
+      mode = WriteMode.Create
+    }
+    const tbl = await tableCreate.call(this._db, name, await fromRecordsToBuffer(data, embeddings), mode.toLowerCase())
     if (embeddings !== undefined) {
       return new LocalTable(tbl, name, embeddings)
     } else {
@@ -445,8 +454,15 @@ export class Query<T = number[]> {
   }
 }
 
+/**
+ * Write mode for writing a table.
+ */
 export enum WriteMode {
+  /** Create a new {@link Table}. */
+  Create = 'create',
+  /** Overwrite the existing {@link Table} if presented. */
   Overwrite = 'overwrite',
+  /** Append new data to the table. */
   Append = 'append'
 }
 

node/src/test/test.ts

@@ -1,4 +1,4 @@
-// Copyright 2023 Lance Developers.
+// Copyright 2023 LanceDB Developers.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,7 +18,7 @@ import * as chai from 'chai'
 import * as chaiAsPromised from 'chai-as-promised'
 
 import * as lancedb from '../index'
-import { type EmbeddingFunction, MetricType, Query } from '../index'
+import { type EmbeddingFunction, MetricType, Query, WriteMode } from '../index'
 
 const expect = chai.expect
 const assert = chai.assert
@@ -118,6 +118,31 @@ describe('LanceDB client', function () {
       assert.equal(await table.countRows(), 2)
     })
 
+    it('use overwrite flag to overwrite existing table', async function () {
+      const dir = await track().mkdir('lancejs')
+      const con = await lancedb.connect(dir)
+
+      const data = [
+        { id: 1, vector: [0.1, 0.2], price: 10 },
+        { id: 2, vector: [1.1, 1.2], price: 50 }
+      ]
+
+      const tableName = 'overwrite'
+      await con.createTable(tableName, data, WriteMode.Create)
+
+      const newData = [
+        { id: 1, vector: [0.1, 0.2], price: 10 },
+        { id: 2, vector: [1.1, 1.2], price: 50 },
+        { id: 3, vector: [1.1, 1.2], price: 50 }
+      ]
+
+      await expect(con.createTable(tableName, newData)).to.be.rejectedWith(Error, 'already exists')
+
+      const table = await con.createTable(tableName, newData, WriteMode.Overwrite)
+      assert.equal(table.name, tableName)
+      assert.equal(await table.countRows(), 3)
+    })
+
     it('appends records to an existing table ', async function () {
       const dir = await track().mkdir('lancejs')
       const con = await lancedb.connect(dir)
@@ -218,7 +243,7 @@ describe('LanceDB client', function () {
         { price: 10, name: 'foo' },
         { price: 50, name: 'bar' }
       ]
-      const table = await con.createTable('vectors', data, embeddings)
+      const table = await con.createTable('vectors', data, WriteMode.Create, embeddings)
       const results = await table.search('foo').execute()
       assert.equal(results.length, 2)
     })