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

***

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

# Class: `abstract` Table

A Table is a collection of Records in a LanceDB Database.

A Table object is expected to be long lived and reused for multiple operations.
Table objects will cache a certain amount of index data in memory.  This cache
will be freed when the Table is garbage collected.  To eagerly free the cache you
can call the `close` method.  Once the Table is closed, it cannot be used for any
further operations.

Tables are created using the methods [Connection#createTable](Connection.md#createtable)
and [Connection#createEmptyTable](Connection.md#createemptytable). Existing tables are opened
using [Connection#openTable](Connection.md#opentable).

Closing a table is optional.  It not closed, it will be closed when it is garbage
collected.

## Accessors

### name

```ts
get abstract name(): string
```

Returns the name of the table

#### Returns

`string`

## Methods

### add()

```ts
abstract add(data, options?): Promise<AddResult>
```

Insert records into this Table.

#### Parameters

* **data**: [`Data`](../type-aliases/Data.md)
    Records to be inserted into the Table

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

#### Returns

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

A promise that resolves to an object
containing the new version number of the table

***

### addColumns()

```ts
abstract addColumns(newColumnTransforms): Promise<AddColumnsResult>
```

Add new columns with defined values.

#### Parameters

* **newColumnTransforms**: `Field`&lt;`any`&gt; \| `Field`&lt;`any`&gt;[] \| `Schema`&lt;`any`&gt; \| [`AddColumnsSql`](../interfaces/AddColumnsSql.md)[]
    Either:
    - An array of objects with column names and SQL expressions to calculate values
    - A single Arrow Field defining one column with its data type (column will be initialized with null values)
    - An array of Arrow Fields defining columns with their data types (columns will be initialized with null values)
    - An Arrow Schema defining columns with their data types (columns will be initialized with null values)

#### Returns

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

A promise that resolves to an object
containing the new version number of the table after adding the columns.

***

### alterColumns()

```ts
abstract alterColumns(columnAlterations): Promise<AlterColumnsResult>
```

Alter the name or nullability of columns.

#### Parameters

* **columnAlterations**: [`ColumnAlteration`](../interfaces/ColumnAlteration.md)[]
    One or more alterations to
    apply to columns.

#### Returns

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

A promise that resolves to an object
containing the new version number of the table after altering the columns.

***

### checkout()

```ts
abstract checkout(version): Promise<void>
```

Checks out a specific version of the table _This is an in-place operation._

This allows viewing previous versions of the table. If you wish to
keep writing to the dataset starting from an old version, then use
the `restore` function.

Calling this method will set the table into time-travel mode. If you
wish to return to standard mode, call `checkoutLatest`.

#### Parameters

* **version**: `string` \| `number`
    The version to checkout, could be version number or tag

#### Returns

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

#### Example

```typescript
import * as lancedb from "@lancedb/lancedb"
const db = await lancedb.connect("./.lancedb");
const table = await db.createTable("my_table", [
  { vector: [1.1, 0.9], type: "vector" },
]);

console.log(await table.version()); // 1
console.log(table.display());
await table.add([{ vector: [0.5, 0.2], type: "vector" }]);
await table.checkout(1);
console.log(await table.version()); // 2
```

***

### checkoutLatest()

```ts
abstract checkoutLatest(): Promise<void>
```

Checkout the latest version of the table. _This is an in-place operation._

The table will be set back into standard mode, and will track the latest
version of the table.

#### Returns

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

***

### close()

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

Close the table, releasing any underlying resources.

It is safe to call this method multiple times.

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

#### Returns

`void`

***

### countRows()

```ts
abstract countRows(filter?): Promise<number>
```

Count the total number of rows in the dataset.

#### Parameters

* **filter?**: `string`

#### Returns

`Promise`&lt;`number`&gt;

***

### createIndex()

```ts
abstract createIndex(column, options?): Promise<void>
```

Create an index to speed up queries.

Indices can be created on vector columns or scalar columns.
Indices on vector columns will speed up vector searches.
Indices on scalar columns will speed up filtering (in both
vector and non-vector searches)

We currently don't support custom named indexes.
The index name will always be `${column}_idx`.

#### Parameters

* **column**: `string`

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

#### Returns

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

#### Examples

```ts
// If the column has a vector (fixed size list) data type then
// an IvfPq vector index will be created.
const table = await conn.openTable("my_table");
await table.createIndex("vector");
```

```ts
// For advanced control over vector index creation you can specify
// the index type and options.
const table = await conn.openTable("my_table");
await table.createIndex("vector", {
  config: lancedb.Index.ivfPq({
    numPartitions: 128,
    numSubVectors: 16,
  }),
});
```

```ts
// Or create a Scalar index
await table.createIndex("my_float_col");
```

***

### delete()

```ts
abstract delete(predicate): Promise<DeleteResult>
```

Delete the rows that satisfy the predicate.

#### Parameters

* **predicate**: `string`

#### Returns

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

A promise that resolves to an object
containing the new version number of the table

***

### display()

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

Return a brief description of the table

#### Returns

`string`

***

### dropColumns()

```ts
abstract dropColumns(columnNames): Promise<DropColumnsResult>
```

Drop one or more columns from the dataset

This is a metadata-only operation and does not remove the data from the
underlying storage. In order to remove the data, you must subsequently
call ``compact_files`` to rewrite the data without the removed columns and
then call ``cleanup_files`` to remove the old files.

#### Parameters

* **columnNames**: `string`[]
    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`&lt;[`DropColumnsResult`](../interfaces/DropColumnsResult.md)&gt;

A promise that resolves to an object
containing the new version number of the table after dropping the columns.

***

### dropIndex()

```ts
abstract dropIndex(name): Promise<void>
```

Drop an index from the table.

#### Parameters

* **name**: `string`
    The name of the index.
    This does not delete the index from disk, it just removes it from the table.
    To delete the index, run [Table#optimize](Table.md#optimize) after dropping the index.
    Use [Table.listIndices](Table.md#listindices) to find the names of the indices.

#### Returns

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

***

### indexStats()

```ts
abstract indexStats(name): Promise<undefined | IndexStatistics>
```

List all the stats of a specified index

#### Parameters

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

#### Returns

`Promise`&lt;`undefined` \| [`IndexStatistics`](../interfaces/IndexStatistics.md)&gt;

The stats of the index. If the index does not exist, it will return undefined

Use [Table.listIndices](Table.md#listindices) to find the names of the indices.

***

### initialStorageOptions()

```ts
abstract initialStorageOptions(): Promise<undefined | null | Record<string, string>>
```

Get the initial storage options that were passed in when opening this table.

For dynamically refreshed options (e.g., credential vending), use
[Table.latestStorageOptions](Table.md#lateststorageoptions).

Warning: This is an internal API and the return value is subject to change.

#### Returns

`Promise`&lt;`undefined` \| `null` \| `Record`&lt;`string`, `string`&gt;&gt;

The storage options, or undefined if no storage options were configured.

***

### isOpen()

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

Return true if the table has not been closed

#### Returns

`boolean`

***

### latestStorageOptions()

```ts
abstract latestStorageOptions(): Promise<undefined | null | Record<string, string>>
```

Get the latest storage options, refreshing from provider if configured.

This method is useful for credential vending scenarios where storage options
may be refreshed dynamically. If no dynamic provider is configured, this
returns the initial static options.

Warning: This is an internal API and the return value is subject to change.

#### Returns

`Promise`&lt;`undefined` \| `null` \| `Record`&lt;`string`, `string`&gt;&gt;

The storage options, or undefined if no storage options were configured.

***

### listIndices()

```ts
abstract listIndices(): Promise<IndexConfig[]>
```

List all indices that have been created with [Table.createIndex](Table.md#createindex)

#### Returns

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

***

### listVersions()

```ts
abstract listVersions(): Promise<Version[]>
```

List all the versions of the table

#### Returns

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

***

### mergeInsert()

```ts
abstract mergeInsert(on): MergeInsertBuilder
```

#### Parameters

* **on**: `string` \| `string`[]

#### Returns

[`MergeInsertBuilder`](MergeInsertBuilder.md)

***

### optimize()

```ts
abstract optimize(options?): Promise<OptimizeStats>
```

Optimize the on-disk data and indices for better performance.

Modeled after ``VACUUM`` in PostgreSQL.

 Optimization covers three operations:

 - Compaction: Merges small files into larger ones
 - Prune: Removes old versions of the dataset
 - Index: Optimizes the indices, adding new data to existing indices

 The frequency an application should call optimize is based on the frequency of
 data modifications.  If data is frequently added, deleted, or updated then
 optimize should be run frequently.  A good rule of thumb is to run optimize if
 you have added or modified 100,000 or more records or run more than 20 data
 modification operations.

#### Parameters

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

#### Returns

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

***

### prewarmData()

```ts
abstract prewarmData(columns?): Promise<void>
```

Prewarm one or more columns of data in the table.

#### Parameters

* **columns?**: `string`[]
    The columns to prewarm. If undefined, all columns are prewarmed.
    This will load the column data into the page cache so that future queries that
    read those columns avoid the initial cold-start latency.  This call initiates
    prewarming and returns once the request is accepted; the warming itself may
    continue in the background.  Calling it on already-prewarmed columns is a
    no-op on the server.
    Prewarming is generally useful for columns used in filters or projections.
    Large columns (e.g. high-dimensional vectors or binary data) may not be
    practical to prewarm.
    This feature is currently only supported on remote tables.

#### Returns

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

***

### prewarmIndex()

```ts
abstract prewarmIndex(name): Promise<void>
```

Prewarm an index in the table.

#### Parameters

* **name**: `string`
    The name of the index.
    This will load the index into memory.  This may reduce the cold-start time for
    future queries.  If the index does not fit in the cache then this call may be
    wasteful.

#### Returns

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

***

### query()

```ts
abstract query(): Query
```

Create a [Query](Query.md) Builder.

Queries allow you to search your existing data.  By default the query will
return all the data in the table in no particular order.  The builder
returned by this method can be used to control the query using filtering,
vector similarity, sorting, and more.

Note: By default, all columns are returned.  For best performance, you should
only fetch the columns you need.

When appropriate, various indices and statistics based pruning will be used to
accelerate the query.

#### Returns

[`Query`](Query.md)

A builder that can be used to parameterize the query

#### Examples

```ts
// SQL-style filtering
//
// This query will return up to 1000 rows whose value in the `id` column
// is greater than 5. LanceDb supports a broad set of filtering functions.
for await (const batch of table
  .query()
  .where("id > 1")
  .select(["id"])
  .limit(20)) {
  console.log(batch);
}
```

```ts
// Vector Similarity Search
//
// This example will find the 10 rows whose value in the "vector" column are
// closest to the query vector [1.0, 2.0, 3.0].  If an index has been created
// on the "vector" column then this will perform an ANN search.
//
// The `refineFactor` and `nprobes` methods are used to control the recall /
// latency tradeoff of the search.
for await (const batch of table
  .query()
  .where("id > 1")
  .select(["id"])
  .limit(20)) {
  console.log(batch);
}
```

```ts
// Scan the full dataset
//
// This query will return everything in the table in no particular order.
for await (const batch of table.query()) {
  console.log(batch);
}
```

***

### restore()

```ts
abstract restore(): Promise<void>
```

Restore the table to the currently checked out version

This operation will fail if checkout has not been called previously

This operation will overwrite the latest version of the table with a
previous version.  Any changes made since the checked out version will
no longer be visible.

Once the operation concludes the table will no longer be in a checked
out state and the read_consistency_interval, if any, will apply.

#### Returns

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

***

### schema()

```ts
abstract schema(): Promise<Schema<any>>
```

Get the schema of the table.

#### Returns

`Promise`&lt;`Schema`&lt;`any`&gt;&gt;

***

### search()

```ts
abstract search(
   query,
   queryType?,
   ftsColumns?): Query | VectorQuery
```

Create a search query to find the nearest neighbors
of the given query

#### Parameters

* **query**: `string` \| [`IntoVector`](../type-aliases/IntoVector.md) \| [`MultiVector`](../type-aliases/MultiVector.md) \| [`FullTextQuery`](../interfaces/FullTextQuery.md)
    the query, a vector or string

* **queryType?**: `string`
    the type of the query, "vector", "fts", or "auto"

* **ftsColumns?**: `string` \| `string`[]
    the columns to search in for full text search
    for now, only one column can be searched at a time.
    when "auto" is used, if the query is a string and an embedding function is defined, it will be treated as a vector query
    if the query is a string and no embedding function is defined, it will be treated as a full text search query

#### Returns

[`Query`](Query.md) \| [`VectorQuery`](VectorQuery.md)

***

### setLsmWriteSpec()

```ts
abstract setLsmWriteSpec(spec): Promise<void>
```

Install an [LsmWriteSpec](../interfaces/LsmWriteSpec.md) on this table, selecting Lance's MemWAL
LSM-style write path for future `mergeInsert` calls.

`LsmWriteSpec` chooses one of three sharding strategies via `specType`:

- `"bucket"` — hash-bucket writes by the single-column unenforced primary
  key (`column` and `numBuckets` required).
- `"identity"` — shard by the raw value of a scalar `column`.
- `"unsharded"` — route every write to a single shard.

All variants require the table to have an unenforced primary key
([Table#setUnenforcedPrimaryKey](Table.md#setunenforcedprimarykey)); bucket sharding additionally
requires it to be the single column being bucketed.

#### Parameters

* **spec**: [`LsmWriteSpec`](../interfaces/LsmWriteSpec.md)
    The sharding spec to install.

#### Returns

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

#### Example

```ts
await table.setUnenforcedPrimaryKey("id");
await table.setLsmWriteSpec({
  specType: "bucket",
  column: "id",
  numBuckets: 16,
  maintainedIndexes: ["id_idx"],
});
```

***

### setUnenforcedPrimaryKey()

```ts
abstract setUnenforcedPrimaryKey(columns): Promise<void>
```

Set the unenforced primary key for this table to a single column.

"Unenforced" means LanceDB does not check uniqueness on writes; the
column is recorded in the schema as the primary key for use by features
such as `merge_insert`. Only single-column primary keys are supported,
and the key cannot be changed once set.

#### Parameters

* **columns**: `string` \| `string`[]
    The primary key column. A one-element
    array is also accepted; passing more than one column is rejected.

#### Returns

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

***

### stats()

```ts
abstract stats(): Promise<TableStatistics>
```

Returns table and fragment statistics

#### Returns

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

The table and fragment statistics

***

### tags()

```ts
abstract tags(): Promise<Tags>
```

Get a tags manager for this table.

Tags allow you to label specific versions of a table with a human-readable name.
The returned tags manager can be used to list, create, update, or delete tags.

#### Returns

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

A tags manager for this table

#### Example

```typescript
const tagsManager = await table.tags();
await tagsManager.create("v1", 1);
const tags = await tagsManager.list();
console.log(tags); // { "v1": { version: 1, manifestSize: ... } }
```

***

### takeOffsets()

```ts
abstract takeOffsets(offsets): TakeQuery
```

Create a query that returns a subset of the rows in the table.

#### Parameters

* **offsets**: `number`[]
    The offsets of the rows to return.

#### Returns

[`TakeQuery`](TakeQuery.md)

A builder that can be used to parameterize the query.

***

### takeRowIds()

```ts
abstract takeRowIds(rowIds): TakeQuery
```

Create a query that returns a subset of the rows in the table.

#### Parameters

* **rowIds**: readonly (`number` \| `bigint`)[]
    The row ids of the rows to return.
    Row ids returned by `withRowId()` are `bigint`, so `bigint[]` is supported.
    For convenience / backwards compatibility, `number[]` is also accepted (for
    small row ids that fit in a safe integer).

#### Returns

[`TakeQuery`](TakeQuery.md)

A builder that can be used to parameterize the query.

***

### toArrow()

```ts
abstract toArrow(): Promise<Table<any>>
```

Return the table as an arrow table

#### Returns

`Promise`&lt;`Table`&lt;`any`&gt;&gt;

***

### unsetLsmWriteSpec()

```ts
abstract unsetLsmWriteSpec(): Promise<void>
```

Remove the [LsmWriteSpec](../interfaces/LsmWriteSpec.md) from this table, reverting to the standard
`mergeInsert` write path.

Errors if no spec is currently set.

#### Returns

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

***

### update()

#### update(opts)

```ts
abstract update(opts): Promise<UpdateResult>
```

Update existing records in the Table

##### Parameters

* **opts**: `object` & `Partial`&lt;[`UpdateOptions`](../interfaces/UpdateOptions.md)&gt;

##### Returns

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

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]}})
```

#### update(opts)

```ts
abstract update(opts): Promise<UpdateResult>
```

Update existing records in the Table

##### Parameters

* **opts**: `object` & `Partial`&lt;[`UpdateOptions`](../interfaces/UpdateOptions.md)&gt;

##### Returns

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

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"}})
```

#### update(updates, options)

```ts
abstract update(updates, options?): Promise<UpdateResult>
```

Update existing records in the Table

An update operation can be used to adjust existing values.  Use the
returned builder to specify which columns to update.  The new value
can be a literal value (e.g. replacing nulls with some default value)
or an expression applied to the old value (e.g. incrementing a value)

An optional condition can be specified (e.g. "only update if the old
value is 0")

Note: if your condition is something like "some_id_column == 7" and
you are updating many rows (with different ids) then you will get
better performance with a single [`merge_insert`] call instead of
repeatedly calilng this method.

##### Parameters

* **updates**: `Record`&lt;`string`, `string`&gt; \| `Map`&lt;`string`, `string`&gt;
    the
    columns to update

* **options?**: `Partial`&lt;[`UpdateOptions`](../interfaces/UpdateOptions.md)&gt;
    additional options to control
    the update behavior

##### Returns

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

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
be SQL literal strings (e.g. "7" or "'foo'") or they can be expressions
based on the row being updated (e.g. "my_col + 1")

***

### vectorSearch()

```ts
abstract vectorSearch(vector): VectorQuery
```

Search the table with a given query vector.

This is a convenience method for preparing a vector query and
is the same thing as calling `nearestTo` on the builder returned
by `query`.

#### Parameters

* **vector**: [`IntoVector`](../type-aliases/IntoVector.md) \| [`MultiVector`](../type-aliases/MultiVector.md)

#### Returns

[`VectorQuery`](VectorQuery.md)

#### See

[Query#nearestTo](Query.md#nearestto) for more details.

***

### version()

```ts
abstract version(): Promise<number>
```

Retrieve the version of the table

#### Returns

`Promise`&lt;`number`&gt;

***

### waitForIndex()

```ts
abstract waitForIndex(indexNames, timeoutSeconds): Promise<void>
```

Waits for asynchronous indexing to complete on the table.

#### Parameters

* **indexNames**: `string`[]
    The name of the indices to wait for

* **timeoutSeconds**: `number`
    The number of seconds to wait before timing out
    This will raise an error if the indices are not created and fully indexed within the timeout.

#### Returns

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