From 21245dfb9d76ede89ff359e694000ec456d91f44 Mon Sep 17 00:00:00 2001
From: QianZhu <qian@lancedb.com>
Date: Wed, 3 Jan 2024 16:24:21 -0800
Subject: [PATCH] SaaS JS API sdk doc (#740)

Co-authored-by: Aidan <64613310+aidangomar@users.noreply.github.com>
---
 .github/workflows/docs_test.yml               |   3 +
 docs/mkdocs.yml                               |   1 +
 docs/src/ann_indexes.md                       |   2 +
 .../javascript/classes/RemoteConnection.md    | 226 +++++++++++
 docs/src/javascript/classes/RemoteQuery.md    |  76 ++++
 docs/src/javascript/classes/RemoteTable.md    | 355 ++++++++++++++++++
 docs/src/javascript/saas-modules.md           |  92 +++++
 7 files changed, 755 insertions(+)
 create mode 100644 docs/src/javascript/classes/RemoteConnection.md
 create mode 100644 docs/src/javascript/classes/RemoteQuery.md
 create mode 100644 docs/src/javascript/classes/RemoteTable.md
 create mode 100644 docs/src/javascript/saas-modules.md

diff --git a/.github/workflows/docs_test.yml b/.github/workflows/docs_test.yml
index 084d563b..661e954f 100644
--- a/.github/workflows/docs_test.yml
+++ b/.github/workflows/docs_test.yml
@@ -88,6 +88,9 @@ jobs:
         cd docs/test
         node md_testing.js
     - name: Test
+      env:
+        LANCEDB_URI: ${{ secrets.LANCEDB_URI }}
+        LANCEDB_DEV_API_KEY: ${{ secrets.LANCEDB_DEV_API_KEY }}
       run: |
         cd docs/test/node
         for d in *; do cd "$d"; echo "$d".js; node "$d".js; cd ..; done
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index d25fc36c..e065e1ed 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -147,6 +147,7 @@ nav:
   - OSS Python API: python/python.md
   - SaaS Python API: python/saas-python.md
   - Javascript API: javascript/modules.md
+  - SaaS Javascript API: javascript/saas-modules.md
 - LanceDB Cloud↗: https://noteforms.com/forms/lancedb-mailing-list-cloud-kty1o5?notionforms=1&utm_source=notionforms
 
 extra_css:
diff --git a/docs/src/ann_indexes.md b/docs/src/ann_indexes.md
index 6e9b7ac3..13b59d40 100644
--- a/docs/src/ann_indexes.md
+++ b/docs/src/ann_indexes.md
@@ -164,6 +164,7 @@ You can further filter the elements returned by a search using a where clause.
      const results_2 = await table
          .search(Array(1536).fill(1.2))
          .where("id != '1141'")
+         .limit(2)
          .execute()
      ```
 
@@ -187,6 +188,7 @@ You can select the columns returned by the query using a select clause.
      const results_3 = await table
          .search(Array(1536).fill(1.2))
          .select(["id"])
+         .limit(2)
          .execute()
      ```
 
diff --git a/docs/src/javascript/classes/RemoteConnection.md b/docs/src/javascript/classes/RemoteConnection.md
new file mode 100644
index 00000000..a3b627d7
--- /dev/null
+++ b/docs/src/javascript/classes/RemoteConnection.md
@@ -0,0 +1,226 @@
+[vectordb](../README.md) / [Exports](../saas-modules.md) / RemoteConnection
+
+# Class: RemoteConnection
+
+A connection to a remote LanceDB database. The class RemoteConnection implements interface Connection
+
+## Implements
+
+- [`Connection`](../interfaces/Connection.md)
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RemoteConnection.md#constructor)
+
+### Methods
+
+- [createTable](RemoteConnection.md#createtable)
+- [tableNames](RemoteConnection.md#tablenames)
+- [openTable](RemoteConnection.md#opentable)
+- [dropTable](RemoteConnection.md#droptable)
+
+
+## Constructors
+
+### constructor
+
+• **new RemoteConnection**(`client`, `dbName`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `client` | `HttpLancedbClient` |
+| `dbName` | `string` |
+
+#### Defined in
+
+[remote/index.ts:37](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L37)
+
+## Methods
+
+### createTable
+
+▸ **createTable**(`name`, `data`, `mode?`): `Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+Creates a new Table and initialize it with new data.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `name` | `string` | The name of the table. |
+| `data` | `Record`<`string`, `unknown`\>[] | Non-empty Array of Records to be inserted into the Table |
+| `mode?` | [`WriteMode`](../enums/WriteMode.md) | The write mode to use when creating the table. |
+
+#### Returns
+
+`Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+#### Implementation of
+
+[Connection](../interfaces/Connection.md).[createTable](../interfaces/Connection.md#createtable)
+
+#### Defined in
+
+[remote/index.ts:75](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L75)
+
+▸ **createTable**(`name`, `data`, `mode`): `Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `name` | `string` |
+| `data` | `Record`<`string`, `unknown`\>[] |
+| `mode` | [`WriteMode`](../enums/WriteMode.md) |
+| `embeddings` | [`EmbeddingFunction`](../interfaces/EmbeddingFunction.md)<`T`\> | An embedding function to use on this Table |
+
+#### Returns
+
+`Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+#### Implementation of
+
+Connection.createTable
+
+#### Defined in
+
+[remote/index.ts:231](https://github.com/lancedb/lancedb/blob/b1eeb90/node/src/index.ts#L231)
+
+___
+
+### dropTable
+
+▸ **dropTable**(`name`): `Promise`<`void`\>
+
+Drop an existing table.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `name` | `string` | The name of the table to drop. |
+
+#### Returns
+
+`Promise`<`void`\>
+
+#### Implementation of
+
+[Connection](../interfaces/Connection.md).[dropTable](../interfaces/Connection.md#droptable)
+
+#### Defined in
+
+[remote/index.ts:131](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L131)
+
+___
+
+### openTable
+
+▸ **openTable**(`name`): `Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+Open a table in the database.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `name` | `string` | The name of the table. |
+
+#### Returns
+
+`Promise`<[`Table`](../interfaces/Table.md)<`number`[]\>\>
+
+#### Implementation of
+
+[Connection](../interfaces/Connection.md).[openTable](../interfaces/Connection.md#opentable)
+
+#### Defined in
+
+[remote/index.ts:65](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L65)
+
+▸ **openTable**<`T`\>(`name`, `embeddings`): `Promise`<[`Table`](../interfaces/Table.md)<`T`\>\>
+
+Open a table in the database.
+
+#### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `name` | `string` | The name of the table. |
+| `embeddings` | [`EmbeddingFunction`](../interfaces/EmbeddingFunction.md)<`T`\> | An embedding function to use on this Table |
+
+#### Returns
+
+`Promise`<[`Table`](../interfaces/Table.md)<`T`\>\>
+
+#### Implementation of
+
+Connection.openTable
+
+#### Defined in
+
+[remote/index.ts:66](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L66)
+
+▸ **openTable**<`T`\>(`name`, `embeddings?`): `Promise`<[`Table`](../interfaces/Table.md)<`T`\>\>
+
+#### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `name` | `string` |
+| `embeddings?` | [`EmbeddingFunction`](../interfaces/EmbeddingFunction.md)<`T`\> |
+
+#### Returns
+
+`Promise`<[`Table`](../interfaces/Table.md)<`T`\>\>
+
+#### Implementation of
+
+Connection.openTable
+
+#### Defined in
+
+[remote/index.ts:67](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L67)
+
+___
+
+### tableNames
+
+▸ **tableNames**(): `Promise`<`string`[]\>
+
+Get the names of all tables in the database, with pagination.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `pageToken` | `string` |
+| `limit` | `int` |
+
+#### Returns
+
+`Promise`<`string`[]\>
+
+#### Implementation of
+
+[Connection](../interfaces/Connection.md).[tableNames](../interfaces/Connection.md#tablenames)
+
+#### Defined in
+
+[remote/index.ts:60](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L60)
diff --git a/docs/src/javascript/classes/RemoteQuery.md b/docs/src/javascript/classes/RemoteQuery.md
new file mode 100644
index 00000000..4ff7d366
--- /dev/null
+++ b/docs/src/javascript/classes/RemoteQuery.md
@@ -0,0 +1,76 @@
+[vectordb](../README.md) / [Exports](../saas-modules.md) / RemoteQuery
+
+# Class: Query<T\>
+
+A builder for nearest neighbor queries for LanceDB.
+
+## Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `number`[] |
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RemoteQuery.md#constructor)
+
+### Properties
+
+- [\_embeddings](RemoteQuery.md#_embeddings)
+- [\_query](RemoteQuery.md#_query)
+- [\_name](RemoteQuery.md#_name)
+- [\_client](RemoteQuery.md#_client)
+
+### Methods
+
+- [execute](RemoteQuery.md#execute)
+
+
+## Constructors
+
+### constructor
+
+• **new Query**<`T`\>(`name`, `client`, `query`, `embeddings?`)
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `number`[] |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `name` | `string` |
+| `client` | `HttpLancedbClient` |
+| `query` | `T` |
+| `embeddings?` | [`EmbeddingFunction`](../interfaces/EmbeddingFunction.md)<`T`\> |
+
+#### Defined in
+
+[remote/index.ts:137](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L137)
+
+## Methods
+
+### execute
+
+▸ **execute**<`T`\>(): `Promise`<`T`[]\>
+
+Execute the query and return the results as an Array of Objects
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `Record`<`string`, `unknown`\> |
+
+#### Returns
+
+`Promise`<`T`[]\>
+
+#### Defined in
+
+[remote/index.ts:143](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L143)
\ No newline at end of file
diff --git a/docs/src/javascript/classes/RemoteTable.md b/docs/src/javascript/classes/RemoteTable.md
new file mode 100644
index 00000000..5c176207
--- /dev/null
+++ b/docs/src/javascript/classes/RemoteTable.md
@@ -0,0 +1,355 @@
+[vectordb](../README.md) / [Exports](../saas-modules.md) / RemoteTable
+
+# Class: RemoteTable<T\>
+
+A LanceDB Table is the collection of Records. Each Record has one or more vector fields.
+
+## Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `number`[] |
+
+## Implements
+
+- [`Table`](../interfaces/Table.md)<`T`\>
+
+## Table of contents
+
+### Constructors
+
+- [constructor](RemoteTable.md#constructor)
+
+### Properties
+
+- [\_name](RemoteTable.md#_name)
+- [\_client](RemoteTable.md#_client)
+- [\_embeddings](RemoteTable.md#_embeddings)
+
+### Accessors
+
+- [name](RemoteTable.md#name)
+
+### Methods
+
+- [add](RemoteTable.md#add)
+- [countRows](RemoteTable.md#countrows)
+- [createIndex](RemoteTable.md#createindex)
+- [delete](RemoteTable.md#delete)
+- [listIndices](classes/RemoteTable.md#listindices)
+- [indexStats](classes/RemoteTable.md#liststats)
+- [overwrite](RemoteTable.md#overwrite)
+- [search](RemoteTable.md#search)
+- [schema](classes/RemoteTable.md#schema)
+- [update](RemoteTable.md#update)
+
+## Constructors
+
+### constructor
+
+• **new RemoteTable**<`T`\>(`client`, `name`)
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `number`[] |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `client` | `HttpLancedbClient` |
+| `name` | `string` |
+
+#### Defined in
+
+[remote/index.ts:186](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L186)
+
+• **new RemoteTable**<`T`\>(`client`, `name`, `embeddings`)
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `number`[] |
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `client` | `HttpLancedbClient` |  |
+| `name` | `string` |  |
+| `embeddings` | [`EmbeddingFunction`](../interfaces/EmbeddingFunction.md)<`T`\> | An embedding function to use when interacting with this table |
+
+#### Defined in
+
+[remote/index.ts:187](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L187)
+
+## Accessors
+
+### name
+
+• `get` **name**(): `string`
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[name](../interfaces/Table.md#name)
+
+#### Defined in
+
+[remote/index.ts:194](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L194)
+
+## Methods
+
+### add
+
+▸ **add**(`data`): `Promise`<`number`\>
+
+Insert records into this Table.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `data` | `Record`<`string`, `unknown`\>[] | Records to be inserted into the Table |
+
+#### Returns
+
+`Promise`<`number`\>
+
+The number of rows added to the table
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[add](../interfaces/Table.md#add)
+
+#### Defined in
+
+[remote/index.ts:293](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L293)
+
+___
+
+### countRows
+
+▸ **countRows**(): `Promise`<`number`\>
+
+Returns the number of rows in this table.
+
+#### Returns
+
+`Promise`<`number`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[countRows](../interfaces/Table.md#countrows)
+
+#### Defined in
+
+[remote/index.ts:290](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L290)
+
+___
+
+### createIndex
+
+▸ **createIndex**(`metric_type`, `column`, `index_cache_size`): `Promise`<`any`\>
+
+Create an ANN index on this Table vector index.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `metric_type` | `string` | distance metric type, L2 or cosine or dot |
+| `column` | `string` | the name of the column to be indexed |
+
+#### Returns
+
+`Promise`<`any`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[createIndex](../interfaces/Table.md#createindex)
+
+#### Defined in
+
+[remote/index.ts:249](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L249)
+
+___
+
+### delete
+
+▸ **delete**(`filter`): `Promise`<`void`\>
+
+Delete rows from this table.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `filter` | `string` | A filter in the same format used by a sql WHERE clause. |
+
+#### Returns
+
+`Promise`<`void`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[delete](../interfaces/Table.md#delete)
+
+#### Defined in
+
+[remote/index.ts:295](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L295)
+
+___
+
+### overwrite
+
+▸ **overwrite**(`data`): `Promise`<`number`\>
+
+Insert records into this Table, replacing its contents.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `data` | `Record`<`string`, `unknown`\>[] | Records to be inserted into the Table |
+
+#### Returns
+
+`Promise`<`number`\>
+
+The number of rows added to the table
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[overwrite](../interfaces/Table.md#overwrite)
+
+#### Defined in
+
+[remote/index.ts:231](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L231)
+
+___
+
+### search
+
+▸ **search**(`query`): [`Query`](Query.md)<`T`\>
+
+Creates a search query to find the nearest neighbors of the given search term
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `query` | `T` | The query search term |
+
+#### Returns
+
+[`Query`](Query.md)<`T`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[search](../interfaces/Table.md#search)
+
+#### Defined in
+
+[remote/index.ts:209](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L209)
+
+___
+
+### update
+
+▸ **update**(`args`): `Promise`<`void`\>
+
+Update zero to all rows depending on how many rows match the where clause.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `args` | `UpdateArgs` or `UpdateSqlArgs` | The query search arguments |
+
+#### Returns
+
+`Promise`<`any`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[search](../interfaces/Table.md#update)
+
+#### Defined in
+
+[remote/index.ts:299](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L299)
+
+___
+
+### schema
+
+▸ **schema**(): `Promise`<`void`\>
+
+Get the schema of the table
+
+
+#### Returns
+
+`Promise`<`any`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[search](../interfaces/Table.md#schema)
+
+#### Defined in
+
+[remote/index.ts:198](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L198)
+
+___
+
+### listIndices
+
+▸ **listIndices**(): `Promise`<`void`\>
+
+List the indices of the table
+
+
+#### Returns
+
+`Promise`<`any`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[search](../interfaces/Table.md#listIndices)
+
+#### Defined in
+
+[remote/index.ts:319](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L319)
+
+___
+
+### indexStats
+
+▸ **indexStats**(`indexUuid`): `Promise`<`void`\>
+
+Get the indexed/unindexed of rows from the table
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `indexUuid` | `string`  | the uuid of the index |
+
+#### Returns
+
+`Promise`<`numIndexedRows`\>
+`Promise`<`numUnindexedRows`\>
+
+#### Implementation of
+
+[Table](../interfaces/Table.md).[search](../interfaces/Table.md#indexStats)
+
+#### Defined in
+
+[remote/index.ts:328](https://github.com/lancedb/lancedb/blob/main/node/src/remote/index.ts#L328)
\ No newline at end of file
diff --git a/docs/src/javascript/saas-modules.md b/docs/src/javascript/saas-modules.md
new file mode 100644
index 00000000..22253972
--- /dev/null
+++ b/docs/src/javascript/saas-modules.md
@@ -0,0 +1,92 @@
+# Table of contents
+
+## Installation
+
+```bash
+npm install vectordb
+```
+
+This will download the appropriate native library for your platform. We currently
+support x86_64 Linux, aarch64 Linux, Intel MacOS, and ARM (M1/M2) MacOS. We do not
+yet support Windows or musl-based Linux (such as Alpine Linux).
+
+
+## Classes 
+- [RemoteConnection](classes/RemoteConnection.md)
+- [RemoteTable](classes/RemoteTable.md)
+- [RemoteQuery](classes/RemoteQuery.md)
+
+
+## Methods
+
+- [add](classes/RemoteTable.md#add)
+- [countRows](classes/RemoteTable.md#countrows)
+- [createIndex](classes/RemoteTable.md#createindex)
+- [createTable](classes/RemoteConnection.md#createtable)
+- [delete](classes/RemoteTable.md#delete)
+- [dropTable](classes/RemoteConnection.md#droptable)
+- [listIndices](classes/RemoteTable.md#listindices)
+- [indexStats](classes/RemoteTable.md#liststats)
+- [openTable](classes/RemoteConnection.md#opentable)
+- [overwrite](classes/RemoteTable.md#overwrite)
+- [schema](classes/RemoteTable.md#schema)
+- [search](classes/RemoteTable.md#search)
+- [tableNames](classes/RemoteConnection.md#tablenames)
+- [update](classes/RemoteTable.md#update)
+
+
+## Example code 
+```javascript
+
+const lancedb = require('vectordb');
+const { Schema, Field, Int32, Float32, Utf8, FixedSizeList } = require ("apache-arrow/Arrow.node")
+
+// connect to a remote DB
+const devApiKey = process.env.LANCEDB_DEV_API_KEY
+const dbURI = process.env.LANCEDB_URI
+const db = await lancedb.connect({
+  uri: dbURI, // replace dbURI with your project, e.g. "db://your-project-name"
+  apiKey: devApiKey,  // replace dbURI with your api key
+  region: "us-east-1-dev"
+});
+// create a new table
+const tableName = "my_table_000"
+const data = [
+    { id: 1, vector: [0.1, 1.0], item: "foo", price: 10.0 },
+    { id: 2, vector: [3.9, 0.5], item: "bar", price: 20.0 }
+]
+const schema = new Schema(
+    [
+        new Field('id', new Int32()), 
+        new Field('vector', new FixedSizeList(2, new Field('float32', new Float32()))),
+        new Field('item', new Utf8()),
+        new Field('price', new Float32())
+    ]
+)
+const table = await db.createTable({
+    name: tableName,
+    schema,
+}, data)
+
+// list the table
+const tableNames_1 = await db.tableNames('')
+// add some data and search should be okay
+const newData = [
+      { id: 3, vector: [10.3, 1.9], item: "test1", price: 30.0 }, 
+      { id: 4, vector: [6.2, 9.2], item: "test2", price: 40.0 }
+]
+table.add(newData)
+// create the index for the table
+await table.createIndex({
+      metric_type: "L2", 
+      column: "vector"
+})
+let result = await table.search([2.8, 4.3]).select(["vector", "price"]).limit(1).execute()
+// update the data
+await table.update({ 
+      where: "id == 1", 
+      values: { item: "foo1" } 
+})
+//drop the table
+await db.dropTable(tableName)
+```
\ No newline at end of file