lancedb/docs/src/js/classes/Connection.md

[**@lancedb/lancedb**](../README.md) • **Docs**

***

[@lancedb/lancedb](../globals.md) / Connection

# Class: `abstract` Connection

A LanceDB Connection that allows you to open tables and create new ones.

Connection could be local against filesystem or remote against a server.

A Connection is intended to be a long lived object and may hold open
resources such as HTTP connection pools.  This is generally fine and
a single connection should be shared if it is going to be used many
times. However, if you are finished with a connection, you may call
close to eagerly free these resources.  Any call to a Connection
method after it has been closed will result in an error.

Closing a connection is optional.  Connections will automatically
be closed when they are garbage collected.

Any created tables are independent and will continue to work even if
the underlying connection has been closed.

## Methods

### cancelJob()

```ts
abstract cancelJob(jobId): Promise<boolean>
```

Request cancellation of a server-side job by id.

Resolves to true if the server accepted the cancellation, false if no
such job exists. Cancelling an already-terminal job is a no-op success.

#### Parameters

* **jobId**: `string`

#### Returns

`Promise`&lt;`boolean`&gt;

***

### cloneTable()

```ts
abstract cloneTable(
   targetTableName,
   sourceUri,
   options?): Promise<Table>
```

Clone a table from a source table.

A shallow clone creates a new table that shares the underlying data files
with the source table but has its own independent manifest. This allows
both the source and cloned tables to evolve independently while initially
sharing the same data, deletion, and index files.

#### Parameters

* **targetTableName**: `string`
    The name of the target table to create.

* **sourceUri**: `string`
    The URI of the source table to clone from.

* **options?**
    Clone options.

* **options.isShallow?**: `boolean`
    Whether to perform a shallow clone (defaults to true).

* **options.sourceTag?**: `string`
    The tag of the source table to clone.

* **options.sourceVersion?**: `number`
    The version of the source table to clone.

* **options.targetNamespacePath?**: `string`[]
    The namespace path for the target table (defaults to root namespace).

#### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

***

### close()

```ts
abstract close(): void
```

Close the connection, releasing any underlying resources.

It is safe to call this method multiple times.

Any attempt to use the connection after it is closed will result in an error.

#### Returns

`void`

***

### createEmptyTable()

#### createEmptyTable(name, schema, options)

```ts
abstract createEmptyTable(
   name,
   schema,
   options?): Promise<Table>
```

Creates a new empty Table

##### Parameters

* **name**: `string`
    The name of the table.

* **schema**: [`SchemaLike`](../type-aliases/SchemaLike.md)
    The schema of the table

* **options?**: `Partial`&lt;[`CreateTableOptions`](../interfaces/CreateTableOptions.md)&gt;
    Additional options (backwards compatibility)

##### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

#### createEmptyTable(name, schema, namespacePath, options)

```ts
abstract createEmptyTable(
   name,
   schema,
   namespacePath?,
   options?): Promise<Table>
```

Creates a new empty Table

##### Parameters

* **name**: `string`
    The name of the table.

* **schema**: [`SchemaLike`](../type-aliases/SchemaLike.md)
    The schema of the table

* **namespacePath?**: `string`[]
    The namespace path to create the table in (defaults to root namespace)

* **options?**: `Partial`&lt;[`CreateTableOptions`](../interfaces/CreateTableOptions.md)&gt;
    Additional options

##### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

***

### createMaterializedView()

```ts
abstract createMaterializedView(
   name,
   source,
   options?): Promise<MaterializedView>
```

Define a materialized view named `name` over the table `source`.

The view is populated before creation returns. Set `withNoData` to create
only its definition and empty backing table. The view is a normal table:
it can be queried, indexed and searched, and it appears in `tableNames`.
The source table must have stable row ids (create it with
the `newTableEnableStableRowIds` storage option); they keep the view's
provenance valid across source compactions and cannot be enabled after
a table exists.

#### Parameters

* **name**: `string`

* **source**: `string`

* **options?**

* **options.limit?**: `number`

* **options.select?**: [`MaterializedViewSelect`](../type-aliases/MaterializedViewSelect.md)

* **options.where?**: `string`

* **options.withNoData?**: `boolean`

#### Returns

`Promise`&lt;[`MaterializedView`](MaterializedView.md)&gt;

***

### createNamespace()

```ts
abstract createNamespace(namespacePath, options?): Promise<CreateNamespaceResponse>
```

Create a new namespace at the given path.

#### Parameters

* **namespacePath**: `string`[]
    The namespace path to create.

* **options?**: `Partial`&lt;[`CreateNamespaceOptions`](../interfaces/CreateNamespaceOptions.md)&gt;
    Creation `mode`
    ("create" | "exist_ok" | "overwrite") and optional `properties`
    to attach to the namespace.

#### Returns

`Promise`&lt;[`CreateNamespaceResponse`](../interfaces/CreateNamespaceResponse.md)&gt;

The properties of the
  created namespace and an optional transaction id.

***

### createTable()

#### createTable(options, namespacePath)

```ts
abstract createTable(options, namespacePath?): Promise<Table>
```

Creates a new Table and initialize it with new data.

##### Parameters

* **options**: `object` & `Partial`&lt;[`CreateTableOptions`](../interfaces/CreateTableOptions.md)&gt;
    The options object.

* **namespacePath?**: `string`[]
    The namespace path to create the table in (defaults to root namespace)

##### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

#### createTable(name, data, options)

```ts
abstract createTable(
   name,
   data,
   options?): Promise<Table>
```

Creates a new Table and initialize it with new data.

##### Parameters

* **name**: `string`
    The name of the table.

* **data**: [`TableLike`](../type-aliases/TableLike.md) \| `Record`&lt;`string`, `unknown`&gt;[]
    Non-empty Array of Records
    to be inserted into the table

* **options?**: `Partial`&lt;[`CreateTableOptions`](../interfaces/CreateTableOptions.md)&gt;
    Additional options (backwards compatibility)

##### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

#### createTable(name, data, namespacePath, options)

```ts
abstract createTable(
   name,
   data,
   namespacePath?,
   options?): Promise<Table>
```

Creates a new Table and initialize it with new data.

##### Parameters

* **name**: `string`
    The name of the table.

* **data**: [`TableLike`](../type-aliases/TableLike.md) \| `Record`&lt;`string`, `unknown`&gt;[]
    Non-empty Array of Records
    to be inserted into the table

* **namespacePath?**: `string`[]
    The namespace path to create the table in (defaults to root namespace)

* **options?**: `Partial`&lt;[`CreateTableOptions`](../interfaces/CreateTableOptions.md)&gt;
    Additional options

##### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

***

### createView()

```ts
abstract createView(
   name,
   query,
   namespacePath?): Promise<ViewDescription>
```

Create a view: a named query the database plans on every read.

The query is planned once, at creation, so one that cannot be planned is
rejected now rather than at the first read. A view holds no rows, and its
readers see its sources as they are at read time.

There is no replace: a name already taken is an error, and changing a
view is a drop followed by a create.

#### Parameters

* **name**: `string`

* **query**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;[`ViewDescription`](../interfaces/ViewDescription.md)&gt;

***

### describeNamespace()

```ts
abstract describeNamespace(namespacePath): Promise<DescribeNamespaceResponse>
```

Describe a namespace, returning its properties.

#### Parameters

* **namespacePath**: `string`[]
    The namespace path to describe, in
    parent → child order, e.g. `["analytics", "sales"]`.

#### Returns

`Promise`&lt;[`DescribeNamespaceResponse`](../interfaces/DescribeNamespaceResponse.md)&gt;

The namespace's properties
  (may be undefined if the namespace has none).

***

### describeView()

```ts
abstract describeView(name, namespacePath?): Promise<ViewDescription>
```

What this database records about the view named `name`: its defining
query and the schema that query resolved to.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;[`ViewDescription`](../interfaces/ViewDescription.md)&gt;

***

### display()

```ts
abstract display(): string
```

Return a brief description of the connection

#### Returns

`string`

***

### dropAllTables()

```ts
abstract dropAllTables(namespacePath?): Promise<void>
```

Drop all tables in the database.

#### Parameters

* **namespacePath?**: `string`[]
    The namespace path to drop tables from (defaults to root namespace).

#### Returns

`Promise`&lt;`void`&gt;

***

### dropMaterializedView()

```ts
abstract dropMaterializedView(name, namespacePath?): Promise<void>
```

Drop the materialized view named `name`.

The view may become unavailable before physical cleanup finishes. Use
[dropMaterializedViewAsync](Connection.md#dropmaterializedviewasync) to retain and wait for the cleanup job.

Rejects a table that exists but is not a materialized view.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;`void`&gt;

***

### dropMaterializedViewAsync()

```ts
abstract dropMaterializedViewAsync(name, namespacePath?): Promise<Job>
```

Start dropping the materialized view named `name` and return its cleanup
job without waiting for completion.

Rejects a table that exists but is not a materialized view.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;[`Job`](Job.md)&gt;

***

### dropNamespace()

```ts
abstract dropNamespace(namespacePath, options?): Promise<DropNamespaceResponse>
```

Drop a namespace.

Use `behavior: "cascade"` to also drop everything contained in the
namespace (sub-namespaces and tables). The default `"restrict"`
behavior refuses to drop a non-empty namespace.

#### Parameters

* **namespacePath**: `string`[]
    The namespace path to drop.

* **options?**: `Partial`&lt;[`DropNamespaceOptions`](../interfaces/DropNamespaceOptions.md)&gt;
    `mode` ("skip" | "fail"
    for missing-namespace handling) and `behavior` ("restrict" | "cascade").

#### Returns

`Promise`&lt;[`DropNamespaceResponse`](../interfaces/DropNamespaceResponse.md)&gt;

Any properties returned by
  the server and an optional transaction id.

***

### dropTable()

```ts
abstract dropTable(name, namespacePath?): Promise<void>
```

Drop an existing table.

#### Parameters

* **name**: `string`
    The name of the table to drop.

* **namespacePath?**: `string`[]
    The namespace path of the table (defaults to root namespace).

#### Returns

`Promise`&lt;`void`&gt;

***

### dropTableAsync()

```ts
abstract dropTableAsync(name, namespacePath?): Promise<Job>
```

Start dropping a table and return its cleanup job.

The table may become unavailable before its data files are removed. Wait
on the returned job to know when cleanup has finished.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;[`Job`](Job.md)&gt;

***

### dropView()

```ts
abstract dropView(name, namespacePath?): Promise<void>
```

Drop the view named `name` and wait for its definition to be deleted.

The tables it reads are untouched: a view holds no rows of its own. Use
[dropViewAsync](Connection.md#dropviewasync) to retain the cleanup job instead of waiting on it.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;`void`&gt;

***

### dropViewAsync()

```ts
abstract dropViewAsync(name, namespacePath?): Promise<Job>
```

Start dropping the view named `name` and return the job deleting its
definition, without waiting for completion.

The name is free before this resolves. When nothing was bound to it, the
returned job is already finished and has no id.

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;[`Job`](Job.md)&gt;

***

### isOpen()

```ts
abstract isOpen(): boolean
```

Return true if the connection has not been closed

#### Returns

`boolean`

***

### listJobs()

```ts
abstract listJobs(): Promise<JobInfo[]>
```

List server-side jobs across the database's tables.

#### Returns

`Promise`&lt;[`JobInfo`](../interfaces/JobInfo.md)[]&gt;

***

### listMaterializedViews()

```ts
abstract listMaterializedViews(): Promise<string[]>
```

The names of the materialized views in this database.

Found by reading every table's schema, so this costs an open per table.

#### Returns

`Promise`&lt;`string`[]&gt;

***

### listNamespaces()

```ts
abstract listNamespaces(namespacePath?, options?): Promise<ListNamespacesResponse>
```

List the immediate child namespaces under the given parent.

Results may be paginated. To retrieve subsequent pages, pass the
`pageToken` returned by a previous call.

#### Parameters

* **namespacePath?**: `string`[]
    The parent namespace path. Defaults
    to the root namespace if omitted.

* **options?**: `Partial`&lt;[`ListNamespacesOptions`](../interfaces/ListNamespacesOptions.md)&gt;
    Pagination options
    (`pageToken`, `limit`).

#### Returns

`Promise`&lt;[`ListNamespacesResponse`](../interfaces/ListNamespacesResponse.md)&gt;

Child namespace names and
  an optional token for fetching the next page.

***

### listTables()

#### listTables(options)

```ts
abstract listTables(options?): Promise<ListTablesResponse>
```

List a page of the tables in this database.

To retrieve the tables after the page, pass the `pageToken` the response
carries back in. A page can be shorter than `limit` without being the last
one, so walk until a response carries no page token:

```ts
const names = [];
let pageToken = undefined;
do {
  const page = await conn.listTables({ pageToken, limit: 100 });
  names.push(...page.tables);
  pageToken = page.pageToken;
} while (pageToken);
```

##### Parameters

* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
    Pagination options
    (`pageToken`, `limit`).

##### Returns

`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;

A page of table names and an
  optional token for the tables after it.

#### listTables(namespacePath, options)

```ts
abstract listTables(namespacePath?, options?): Promise<ListTablesResponse>
```

List a page of the tables in this database.

##### Parameters

* **namespacePath?**: `string`[]
    The namespace path to list tables from
    (defaults to root namespace)

* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
    Pagination options
    (`pageToken`, `limit`).

##### Returns

`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;

A page of table names and an
  optional token for the tables after it.

***

### listViews()

```ts
abstract listViews(namespacePath?): Promise<string[]>
```

The names of the views in one namespace.

Names only; a definition comes from [describeView](Connection.md#describeview).

#### Parameters

* **namespacePath?**: `string`[]

#### Returns

`Promise`&lt;`string`[]&gt;

***

### openJob()

```ts
abstract openJob(jobId): Promise<Job>
```

Open a server-side job by id, returning a handle with its record already
populated. Rejects when the server has no such job, the way
[Connection.openTable](Connection.md#opentable) does for a missing table.

The returned [Job](Job.md) answers for its own state, specification,
result, failure and event history, so there is no separate
connection-level call for any of them.

#### Parameters

* **jobId**: `string`

#### Returns

`Promise`&lt;[`Job`](Job.md)&gt;

***

### openMaterializedView()

```ts
abstract openMaterializedView(name): Promise<MaterializedView>
```

Open the materialized view named `name`.

Rejects a table that exists but is not a materialized view.

#### Parameters

* **name**: `string`

#### Returns

`Promise`&lt;[`MaterializedView`](MaterializedView.md)&gt;

***

### openTable()

```ts
abstract openTable(
   name,
   namespacePath?,
   options?): Promise<Table>
```

#### Parameters

* **name**: `string`

* **namespacePath?**: `string`[]

* **options?**: `Partial`&lt;[`OpenTableOptions`](../interfaces/OpenTableOptions.md)&gt;

#### Returns

`Promise`&lt;[`Table`](Table.md)&gt;

***

### pauseJob()

```ts
abstract pauseJob(jobId): Promise<string>
```

Pause a server-side job by id.

The job's workers drain and it stays parked until resumed. Resolves to
"pausing", "already_paused", or "committing" -- a job finalizing its
results cannot be parked; retry shortly.

#### Parameters

* **jobId**: `string`

#### Returns

`Promise`&lt;`string`&gt;

***

### renameTable()

```ts
abstract renameTable(
   currentName,
   newName,
   options?): Promise<void>
```

Rename a table.

Currently only supported by LanceDB Cloud. Local OSS connections and
namespace-backed connections (via [connectNamespace](../functions/connectNamespace.md)) reject with
a "not supported" error.

#### Parameters

* **currentName**: `string`
    The current name of the table.

* **newName**: `string`
    The new name for the table.

* **options?**: [`RenameTableOptions`](../interfaces/RenameTableOptions.md)
    Optional namespace paths. When
    `newNamespacePath` is omitted the table stays in `namespacePath`.

#### Returns

`Promise`&lt;`void`&gt;

***

### resumeJob()

```ts
abstract resumeJob(jobId): Promise<string>
```

Resume a paused server-side job by id.

Its workers pick their work back up from checkpoints. Resolves to
"resumed", "still_pausing" -- the pause's worker drain is not confirmed
yet; retry shortly -- or "not_paused".

#### Parameters

* **jobId**: `string`

#### Returns

`Promise`&lt;`string`&gt;

***

### ~~tableNames()~~

#### tableNames(options)

```ts
abstract tableNames(options?): Promise<string[]>
```

List all the table names in this database.

Tables will be returned in lexicographical order.

##### Parameters

* **options?**: `Partial`&lt;[`TableNamesOptions`](../interfaces/TableNamesOptions.md)&gt;
    options to control the
    paging / start point (backwards compatibility)

##### Returns

`Promise`&lt;`string`[]&gt;

##### Deprecated

Use [Connection.listTables](Connection.md#listtables) instead.

#### tableNames(namespacePath, options)

```ts
abstract tableNames(namespacePath?, options?): Promise<string[]>
```

List all the table names in this database.

Tables will be returned in lexicographical order.

##### Parameters

* **namespacePath?**: `string`[]
    The namespace path to list tables from (defaults to root namespace)

* **options?**: `Partial`&lt;[`TableNamesOptions`](../interfaces/TableNamesOptions.md)&gt;
    options to control the
    paging / start point

##### Returns

`Promise`&lt;`string`[]&gt;

##### Deprecated

Use [Connection.listTables](Connection.md#listtables) instead.