@lancedb/lancedb •Docs

@lancedb/lancedb / Query

Class: Query

A builder for LanceDB queries.

See

Table#query,Table#search

Extends

• StandardQueryBase<NativeQuery>

Properties

inner

protectedinner:Query|Promise<Query>;

Inherited from

StandardQueryBase.inner

Methods

analyzePlan()

analyzePlan():Promise<string>

Executes the query and returns the physical query plan annotated with runtime metrics.

This is useful for debugging and performance analysis, as it shows how the query was executedand includes metrics such as elapsed time, rows processed, and I/O statistics.

Returns

Promise<string>

A query execution plan with runtime metrics for each step.

Example

import*aslancedbfrom"@lancedb/lancedb"constdb=awaitlancedb.connect("./.lancedb");consttable=awaitdb.createTable("my_table",[{vector:[1.1,0.9],id:"1"},]);constplan=awaittable.query().nearestTo([0.5,0.2]).analyzePlan();Exampleoutput(withruntimemetricsinlined):AnalyzeExecverbose=true,metrics=[]ProjectionExec:expr=[id@3asid,vector@0asvector,_distance@2as_distance],metrics=[output_rows=1,elapsed_compute=3.292µs]Take:columns="vector, _rowid, _distance, (id)",metrics=[output_rows=1,elapsed_compute=66.001µs,batches_processed=1,bytes_read=8,iops=1,requests=1]CoalesceBatchesExec:target_batch_size=1024,metrics=[output_rows=1,elapsed_compute=3.333µs]GlobalLimitExec:skip=0,fetch=10,metrics=[output_rows=1,elapsed_compute=167ns]FilterExec:_distance@2ISNOTNULL,metrics=[output_rows=1,elapsed_compute=8.542µs]SortExec:TopK(fetch=10),expr=[_distance@2ASCNULLSLAST],metrics=[output_rows=1,elapsed_compute=63.25µs,row_replacements=1]KNNVectorDistance:metric=l2,metrics=[output_rows=1,elapsed_compute=114.333µs,output_batches=1]LanceScan:uri=/path/to/data, projection=[vector], row_id=true, row_addr=false, ordered=false, metrics=[output_rows=1, elapsed_compute=103.626µs, bytes_read=549, iops=2, requests=2]

Inherited from

StandardQueryBase.analyzePlan

execute()

protectedexecute(options?):AsyncGenerator<RecordBatch<any>,void,unknown>

Execute the query and return the results as an

Parameters

• options?:Partial<QueryExecutionOptions>

Returns

AsyncGenerator<RecordBatch<any>,void,unknown>

See

• AsyncIteratorof
• RecordBatch.

By default, LanceDb will use many threads to calculate results and, whenthe result set is large, multiple batches will be processed at one time.This readahead is limited however and backpressure will be applied if thisstream is consumed slowly (this constrains the maximum memory used by asingle query)

Inherited from

StandardQueryBase.execute

explainPlan()

explainPlan(verbose):Promise<string>

Generates an explanation of the query execution plan.

Parameters

• verbose:boolean =false If true, provides a more detailed explanation. Defaults to false.

Returns

Promise<string>

A Promise that resolves to a string containing the query execution plan explanation.

Example

import*aslancedbfrom"@lancedb/lancedb"constdb=awaitlancedb.connect("./.lancedb");consttable=awaitdb.createTable("my_table",[{vector:[1.1,0.9],id:"1"},]);constplan=awaittable.query().nearestTo([0.5,0.2]).explainPlan();

Inherited from

StandardQueryBase.explainPlan

fastSearch()

fastSearch():this

Skip searching un-indexed data. This can make search faster, but will missany data that is not yet indexed.

UseTable#optimize to index all un-indexed data.

Returns

this

Inherited from

StandardQueryBase.fastSearch

filter()

filter(predicate):this

A filter statement to be applied to this query.

Parameters

• predicate:string

Returns

this

See

where

Deprecated

Usewhere instead

Inherited from

StandardQueryBase.filter

fullTextSearch()

fullTextSearch(query,options?):this

Parameters

• query:string |FullTextQuery

• options?:Partial<FullTextSearchOptions>

Returns

this

Inherited from

StandardQueryBase.fullTextSearch

limit()

limit(limit):this

Set the maximum number of results to return.

By default, a plain search has no limit. If this method is notcalled then every valid row from the table will be returned.

Parameters

• limit:number

Returns

this

Inherited from

StandardQueryBase.limit

nearestTo()

nearestTo(vector):VectorQuery

Find the nearest vectors to the given query vector.

This converts the query from a plain query to a vector query.

This method will attempt to convert the input to the query vectorexpected by the embedding model. If the input cannot be convertedthen an error will be thrown.

By default, there is no embedding model, and the input should bean array-like object of numbers (something that can be used as inputto Float32Array.from)

If there is only one vector column (a column whose data type is afixed size list of floats) then the column does not need to be specified.If there is more than one vector column you must use

Parameters

• vector:IntoVector

Returns

VectorQuery

See

• VectorQuery#column to specify which column you would liketo compare with.

If no index has been created on the vector column then a vector querywill perform a distance comparison between the query vector and everyvector in the database and then sort the results. This is sometimescalled a "flat search"

For small databases, with a few hundred thousand vectors or less, this canbe reasonably fast. In larger databases you should create a vector indexon the column. If there is a vector index then an "approximate" nearestneighbor search (frequently called an ANN search) will be performed. Thissearch is much faster, but the results will be approximate.

The query can be further parameterized using the returned builder. Thereare various ANN search parameters that will let you fine tune your recallaccuracy vs search latency.

Vector searches always have alimit. Iflimit has not been called thena defaultlimit of 10 will be used. -Query#limit

nearestToText()

nearestToText(query,columns?):Query

Parameters

• query:string |FullTextQuery

• columns?:string[]

Returns

Query

offset()

offset(offset):this

Set the number of rows to skip before returning results.

This is useful for pagination.

Parameters

• offset:number

Returns

this

Inherited from

StandardQueryBase.offset

outputSchema()

outputSchema():Promise<Schema<any>>

Returns the schema of the output that will be returned by this query.

This can be used to inspect the types and names of the columns that will bereturned by the query before executing it.

Returns

Promise<Schema<any>>

An Arrow Schema describing the output columns.

Inherited from

StandardQueryBase.outputSchema

select()

select(columns):this

Return only the specified columns.

By default a query will return all columns from the table. However, this can havea very significant impact on latency. LanceDb stores data in a columnar fashion. Thismeans we can finely tune our I/O to select exactly the columns we need.

As a best practice you should always limit queries to the columns that you need. If youpass in an array of column names then only those columns will be returned.

You can also use this method to create new "dynamic" columns based on your existing columns.For example, you may not care about "a" or "b" but instead simply want "a + b". This is oftenseen in the SELECT clause of an SQL query (e.g.SELECT a+b FROM my_table).

To create dynamic columns you can pass in a Map. A column will be returnedfor each entry in the map. The key provides the name of the column. The value isan SQL string used to specify how the column is calculated.

For example, an SQL query might stateSELECT a + b AS combined, c. The equivalentinput to this method would be:

Parameters

• columns:string |string[] |Record<string,string> |Map<string,string>

Returns

this

Example

newMap([["combined","a + b"],["c","c"]])Columnswillalwaysbereturnedintheordergiven,evenifthatorderisdifferentthantheorderusedwhenaddingthedata.Notethatyoucanpassina`Record<string, string>`(e.g.anobjectliteral).Thismethoduses`Object.entries`whichshouldpreservetheinsertionorderoftheobject.However,objectinsertionorderiseasytogetwrongand`Map`ismorefoolproof.

Inherited from

StandardQueryBase.select

toArray()

toArray(options?):Promise<any[]>

Collect the results as an array of objects.

Parameters

• options?:Partial<QueryExecutionOptions>

Returns

Promise<any[]>

Inherited from

StandardQueryBase.toArray

toArrow()

toArrow(options?):Promise<Table<any>>

Collect the results as an Arrow

Parameters

• options?:Partial<QueryExecutionOptions>

Returns

Promise<Table<any>>

See

ArrowTable.

Inherited from

StandardQueryBase.toArrow

where()

where(predicate):this

A filter statement to be applied to this query.

The filter should be supplied as an SQL query string. For example:

Parameters

• predicate:string

Returns

this

Example

x>10y>0ANDy<100x>5ORy='test'Filteringperformancecanoftenbeimprovedbycreatingascalarindexonthefiltercolumn(s).

Inherited from

StandardQueryBase.where

withRowId()

withRowId():this

Whether to return the row id in the results.

This column can be used to match results between different queries. Forexample, to match results from a full text search and a vector search inorder to perform hybrid search.

Returns

this

Inherited from

StandardQueryBase.withRowId