Skip to content

@lancedb/lancedb • Docs

@lancedb/lancedb / 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()

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<boolean>

cloneTable()

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<Table>

close()

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)

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

Creates a new empty Table

Parameters

  • name: string The name of the table.

  • schema: SchemaLike The schema of the table

  • options?: Partial<CreateTableOptions> Additional options (backwards compatibility)

Returns

Promise<Table>

createEmptyTable(name, schema, namespacePath, options)

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

Creates a new empty Table

Parameters

  • name: string The name of the table.

  • schema: SchemaLike The schema of the table

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

  • options?: Partial<CreateTableOptions> Additional options

Returns

Promise<Table>

createMaterializedView()

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

Define a materialized view named name over the table source.

LanceDB Embedded creation and refresh require a source build with the experimental-functions Cargo feature, disabled in published packages. LanceDB Enterprise operations do not require this feature.

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.

Parameters

  • name: string

  • source: string

  • options?

  • options.limit?: number

  • options.select?: MaterializedViewSelect

  • options.where?: string

  • options.withNoData?: boolean

Returns

Promise<MaterializedView>

createNamespace()

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

Create a new namespace at the given path.

Parameters

  • namespacePath: string[] The namespace path to create.

  • options?: Partial<CreateNamespaceOptions> Creation mode ("create" | "exist_ok" | "overwrite") and optional properties to attach to the namespace.

Returns

Promise<CreateNamespaceResponse>

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

createTable()

createTable(options, namespacePath)

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

Creates a new Table and initialize it with new data.

Parameters

  • options: object & Partial<CreateTableOptions> The options object.

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

Returns

Promise<Table>

createTable(name, data, options)

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 | Record<string, unknown>[] Non-empty Array of Records to be inserted into the table

  • options?: Partial<CreateTableOptions> Additional options (backwards compatibility)

Returns

Promise<Table>

createTable(name, data, namespacePath, options)

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 | Record<string, unknown>[] 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<CreateTableOptions> Additional options

Returns

Promise<Table>

createView()

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<ViewDescription>

describeNamespace()

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<DescribeNamespaceResponse>

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

describeView()

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<ViewDescription>

display()

abstract display(): string

Return a brief description of the connection

Returns

string

dropAllTables()

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<void>

dropMaterializedView()

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

Drop the materialized view named name.

Remote drops wait for the SQL command to remove the catalog binding. Physical cleanup continues in the background.

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

Parameters

  • name: string

  • namespacePath?: string[]

Returns

Promise<void>

dropMaterializedViewAsync()

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

Start dropping the materialized view named name and return its job. Remote jobs have type query and use the SQL query ID as id. Waiting confirms catalog removal; physical cleanup continues in the background.

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

Parameters

  • name: string

  • namespacePath?: string[]

Returns

Promise<Job>

dropNamespace()

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<DropNamespaceOptions> mode ("skip" | "fail" for missing-namespace handling) and behavior ("restrict" | "cascade").

Returns

Promise<DropNamespaceResponse>

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

dropTable()

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<void>

dropTableAsync()

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<Job>

dropView()

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

Drop the view named name and wait for catalog removal.

The tables it reads are untouched: a view holds no rows of its own. Use dropViewAsync to retain its SQL query job. Completion confirms catalog removal; physical cleanup continues in the background.

Parameters

  • name: string

  • namespacePath?: string[]

Returns

Promise<void>

dropViewAsync()

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

Drop a view and return its SQL query job. The job has type query and its ID is the SQL query UUID. Waiting confirms catalog removal; physical cleanup continues in the background.

Parameters

  • name: string

  • namespacePath?: string[]

Returns

Promise<Job>

isOpen()

abstract isOpen(): boolean

Return true if the connection has not been closed

Returns

boolean

listJobs()

abstract listJobs(options?): Listing<JobInfo>

Iterate lazily over server-side jobs across the database's tables. Use for await...of. Options control page size and the starting token. See Listing for pagination state and error behavior.

Parameters

Returns

Listing<JobInfo>

listMaterializedViews()

abstract listMaterializedViews(options?): Listing<string>

The names of the materialized views in this database.

Iterate lazily with for await...of. Local listings inspect table schemas one page at a time. Options control page size and the starting token. See Listing for pagination state and error behavior.

Parameters

Returns

Listing<string>

listNamespaces()

abstract listNamespaces(namespacePath?, options?): Listing<string>

Lazily list immediate child namespaces, 100 per page by default.

Parameters

Returns

Listing<string>

listTables()

abstract listTables(namespacePath?, options?): Listing<string>

Lazily list tables in a namespace, requesting 100 per page by default.

Parameters

Returns

Listing<string>

Example

for await (const name of conn.listTables([], { pageLimit: 20 })) {
  console.log(name);
}

listViews()

abstract listViews(namespacePath?, options?): Listing<string>

The names of the views in one namespace.

Names only; a definition comes from describeView. Iterate lazily with for await...of. See Listing for pagination state and error behavior; options control page size and the starting token.

Parameters

Returns

Listing<string>

openJob()

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 does for a missing table.

The returned Job 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<Job>

openMaterializedView()

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<MaterializedView>

openTable()

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

Parameters

Returns

Promise<Table>

pauseJob()

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<string>

renameTable()

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

Rename a table.

Supported in LanceDB Enterprise and by namespace backends that implement renaming. Directory namespaces support renaming tables resolved through their manifest, including tables within or across child namespaces. LanceDB Embedded connections and directory-listing root tables 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 Optional namespace paths. When newNamespacePath is omitted the table stays in namespacePath.

Returns

Promise<void>

resumeJob()

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<string>

tableNames()

tableNames(options)

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

List all the table names in this database.

Tables will be returned in lexicographical order.

Parameters
  • options?: Partial<TableNamesOptions> options to control the paging / start point (backwards compatibility)
Returns

Promise<string[]>

Deprecated

Use Connection.listTables instead.

tableNames(namespacePath, options)

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<TableNamesOptions> options to control the paging / start point

Returns

Promise<string[]>

Deprecated

Use Connection.listTables instead.