@lancedb/lancedb •Docs

@lancedb/lancedb / 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 cachewill be freed when the Table is garbage collected. To eagerly free the cache youcan call theclose method. Once the Table is closed, it cannot be used for anyfurther operations.

Tables are created using the methodsConnection#createTableandConnection#createEmptyTable. Existing tables are openedusingConnection#openTable.

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

Accessors

name

getabstractname():string

Returns the name of the table

Returns

string

Methods

add()

abstractadd(data,options?):Promise<AddResult>

Insert records into this Table.

Parameters

• data:Data Records to be inserted into the Table

• options?:Partial<AddDataOptions>

Returns

Promise<AddResult>

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

addColumns()

abstractaddColumns(newColumnTransforms):Promise<AddColumnsResult>

Add new columns with defined values.

Parameters

• newColumnTransforms:AddColumnsSql[] pairs of column names and the SQL expression to use to calculate the value of the new column. These expressions will be evaluated for each row in the table, and can reference existing columns in the table.

Returns

Promise<AddColumnsResult>

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

alterColumns()

abstractalterColumns(columnAlterations):Promise<AlterColumnsResult>

Alter the name or nullability of columns.

Parameters

• columnAlterations:ColumnAlteration[] One or more alterations to apply to columns.

Returns

Promise<AlterColumnsResult>

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

checkout()

abstractcheckout(version):Promise<void>

Checks out a specific version of the tableThis is an in-place operation.

This allows viewing previous versions of the table. If you wish tokeep writing to the dataset starting from an old version, then usetherestore function.

Calling this method will set the table into time-travel mode. If youwish to return to standard mode, callcheckoutLatest.

Parameters

• version:string |number The version to checkout, could be version number or tag

Returns

Promise<void>

Example

import*aslancedbfrom"@lancedb/lancedb"constdb=awaitlancedb.connect("./.lancedb");consttable=awaitdb.createTable("my_table",[{vector:[1.1,0.9],type:"vector"},]);console.log(awaittable.version());// 1console.log(table.display());awaittable.add([{vector:[0.5,0.2],type:"vector"}]);awaittable.checkout(1);console.log(awaittable.version());// 2

checkoutLatest()

abstractcheckoutLatest():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 latestversion of the table.

Returns

Promise<void>

close()

abstractclose():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()

abstractcountRows(filter?):Promise<number>

Count the total number of rows in the dataset.

Parameters

• filter?:string

Returns

Promise<number>

createIndex()

abstractcreateIndex(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 bothvector 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<IndexOptions>

Returns

Promise<void>

Examples

// If the column has a vector (fixed size list) data type then// an IvfPq vector index will be created.consttable=awaitconn.openTable("my_table");awaittable.createIndex("vector");

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

// Or create a Scalar indexawaittable.createIndex("my_float_col");

delete()

abstractdelete(predicate):Promise<DeleteResult>

Delete the rows that satisfy the predicate.

Parameters

• predicate:string

Returns

Promise<DeleteResult>

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

display()

abstractdisplay():string

Return a brief description of the table

Returns

string

dropColumns()

abstractdropColumns(columnNames):Promise<DropColumnsResult>

Drop one or more columns from the dataset

This is a metadata-only operation and does not remove the data from theunderlying storage. In order to remove the data, you must subsequentlycallcompact_files to rewrite the data without the removed columns andthen callcleanup_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<DropColumnsResult>

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

dropIndex()

abstractdropIndex(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, runTable#optimize after dropping the index. UseTable.listIndices to find the names of the indices.

Returns

Promise<void>

indexStats()

abstractindexStats(name):Promise<undefined|IndexStatistics>

List all the stats of a specified index

Parameters

• name:string The name of the index.

Returns

Promise<undefined |IndexStatistics>

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

UseTable.listIndices to find the names of the indices.

isOpen()

abstractisOpen():boolean

Return true if the table has not been closed

Returns

boolean

listIndices()

abstractlistIndices():Promise<IndexConfig[]>

List all indices that have been created withTable.createIndex

Returns

Promise<IndexConfig[]>

listVersions()

abstractlistVersions():Promise<Version[]>

List all the versions of the table

Returns

Promise<Version[]>

mergeInsert()

abstractmergeInsert(on):MergeInsertBuilder

Parameters

• on:string |string[]

Returns

MergeInsertBuilder

optimize()

abstractoptimize(options?):Promise<OptimizeStats>

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

Modeled afterVACUUM 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

Experimental API

The optimization process is undergoing active development and may change. Our goal with these changes is to improve the performance of optimization and reduce the complexity.

That being said, it is essential today to run optimize if you want the best performance. It should be stable and safe to use in production, but it our hope that the API may be simplified (or not even need to be called) in the future.

The frequency an application shoudl 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<OptimizeOptions>

Returns

Promise<OptimizeStats>

prewarmIndex()

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

query()

abstractquery():Query

Create aQuery Builder.

Queries allow you to search your existing data. By default the query willreturn all the data in the table in no particular order. The builderreturned 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 shouldonly fetch the columns you need.

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

Returns

Query

A builder that can be used to parameterize the query

Examples

// 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.forawait(constbatchoftable.query().where("id > 1").select(["id"]).limit(20)){console.log(batch);}

// 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.forawait(constbatchoftable.query().where("id > 1").select(["id"]).limit(20)){console.log(batch);}

// Scan the full dataset//// This query will return everything in the table in no particular order.forawait(constbatchoftable.query()){console.log(batch);}

restore()

abstractrestore():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 aprevious version. Any changes made since the checked out version willno longer be visible.

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

Returns

Promise<void>

schema()

abstractschema():Promise<Schema<any>>

Get the schema of the table.

Returns

Promise<Schema<any>>

search()

abstractsearch(query,queryType?,ftsColumns?):Query|VectorQuery

Create a search query to find the nearest neighborsof the given query

Parameters

• query:string |IntoVector |MultiVector |FullTextQuery 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 |VectorQuery

stats()

abstractstats():Promise<TableStatistics>

Returns table and fragment statistics

Returns

Promise<TableStatistics>

The table and fragment statistics

tags()

abstracttags():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<Tags>

A tags manager for this table

Example

consttagsManager=awaittable.tags();awaittagsManager.create("v1",1);consttags=awaittagsManager.list();console.log(tags);// { "v1": { version: 1, manifestSize: ... } }

takeOffsets()

abstracttakeOffsets(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

A builder that can be used to parameterize the query.

takeRowIds()

abstracttakeRowIds(rowIds):TakeQuery

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

Parameters

• rowIds:number[] The row ids of the rows to return.

Returns

TakeQuery

A builder that can be used to parameterize the query.

toArrow()

abstracttoArrow():Promise<Table<any>>

Return the table as an arrow table

Returns

Promise<Table<any>>

update()

update(opts)

abstractupdate(opts):Promise<UpdateResult>

Update existing records in the Table

Parameters

• opts:object &Partial<UpdateOptions>

Returns

Promise<UpdateResult>

A promise that resolves to an object containingthe number of rows updated and the new version number

Example

table.update({where:"x = 2",values:{"vector":[10,10]}})

update(opts)

abstractupdate(opts):Promise<UpdateResult>

Update existing records in the Table

Parameters

• opts:object &Partial<UpdateOptions>

Returns

Promise<UpdateResult>

A promise that resolves to an object containingthe number of rows updated and the new version number

Example

table.update({where:"x = 2",valuesSql:{"x":"x + 1"}})

update(updates, options)

abstractupdate(updates,options?):Promise<UpdateResult>

Update existing records in the Table

An update operation can be used to adjust existing values. Use thereturned builder to specify which columns to update. The new valuecan 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 oldvalue is 0")

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

Parameters

• updates:Record<string,string> |Map<string,string> the columns to update

• options?:Partial<UpdateOptions> additional options to control the update behavior

Returns

Promise<UpdateResult>

A promise that resolves to an objectcontaining 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 canbe SQL literal strings (e.g. "7" or "'foo'") or they can be expressionsbased on the row being updated (e.g. "my_col + 1")

vectorSearch()

abstractvectorSearch(vector):VectorQuery

Search the table with a given query vector.

This is a convenience method for preparing a vector query andis the same thing as callingnearestTo on the builder returnedbyquery.

Parameters

• vector:IntoVector |MultiVector

Returns

VectorQuery

See

Query#nearestTo for more details.

version()

abstractversion():Promise<number>

Retrieve the version of the table

Returns

Promise<number>

waitForIndex()

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