@lancedb/lancedb •Docs

@lancedb/lancedb / TakeQuery

Class: TakeQuery

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

Extends

• QueryBase<NativeTakeQuery>

Properties

inner

protectedinner:TakeQuery|Promise<TakeQuery>;

Inherited from

QueryBase.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

QueryBase.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

QueryBase.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

QueryBase.explainPlan

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

QueryBase.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

QueryBase.select

toArray()

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

Collect the results as an array of objects.

Parameters

• options?:Partial<QueryExecutionOptions>

Returns

Promise<any[]>

Inherited from

QueryBase.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

QueryBase.toArrow

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

QueryBase.withRowId