Lance vector store

The LanceVectorStore class provides vector search using LanceDB, an embedded vector database built on the Lance columnar format. It offers efficient storage and fast similarity search for both local development and production deployments.

Factory method

The LanceVectorStore uses a factory pattern for creation. You should use the static create() method rather than the constructor directly.

uri:

string

Path to LanceDB database or URI for cloud deployments

options?:

ConnectionOptions

Additional connection options for LanceDB

Constructor examples

You can create a LanceVectorStore instance using the static create method:

import { LanceVectorStore } from '@mastra/lance'

// Connect to a local database
const vectorStore = await LanceVectorStore.create('/path/to/db')

// Connect to a LanceDB cloud database
const cloudStore = await LanceVectorStore.create('db://host:port')

// Connect to a cloud database with options
const s3Store = await LanceVectorStore.create('s3://bucket/db', {
  storageOptions: { timeout: '60s' },
})

Methods

createIndex()

tableName:

string

Name of the table to create index in

indexName:

string

Name of the index (column name) to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search

indexConfig?:

LanceIndexConfig

= { type: 'hnsw' }

Index configuration

LanceIndexConfig

type:

'ivfflat' | 'ivfpq' | 'hnsw'

= hnsw

Index type

string

ivfflat:

ivfflat

Clusters vectors into partitions and stores full vectors. Searches compute exact distances only within the probed partitions, so closer vectors in other partitions can be missed.

ivfpq:

ivfpq

IVF index with product quantization. Uses less memory than ivfflat with lower recall.

hnsw:

hnsw

Graph-based index offering fast search times and high recall.

numPartitions?:

number

= 128

Number of partitions for IVF indexes

numSubVectors?:

number

= 16

Number of sub-vectors for product quantization. Only applies to ivfpq

hnsw?:

HNSWConfig

HNSW configuration

object

m?:

number

Maximum number of connections per node (default: 16)

efConstruction?:

number

Build-time complexity (default: 100)

createTable()

tableName:

string

Name of the table to create

data:

Record<string, unknown>[] | TableLike

Initial data for the table

options?:

Partial<CreateTableOptions>

Additional table creation options

upsert()

tableName:

string

Name of the table to upsert vectors into

vectors:

number[][]

Array of embedding vectors

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

Optional vector IDs (auto-generated if not provided)

query()

tableName:

string

Name of the table to query

queryVector:

number[]

Query vector

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters

includeVector?:

boolean

= false

Whether to include the vector in the result

columns?:

string[]

= []

Specific columns to include in the result

includeAllColumns?:

boolean

= false

Whether to include all columns in the result

listTables()

Returns an array of table names as strings.

const tables = await vectorStore.listTables()
// ['my_vectors', 'embeddings', 'documents']

getTableSchema()

tableName:

string

Name of the table to describe

Returns the schema of the specified table.

deleteTable()

tableName:

string

Name of the table to delete

deleteAllTables()

Deletes all tables in the database.

listIndexes()

Returns an array of index names as strings.

describeIndex()

indexName:

string

Name of the index to describe

Returns information about the index:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

getIndexCoverage()

tableName?:

string

Table to inspect. Defaults to indexName when omitted.

indexName?:

string

Used as the table name when tableName is omitted, matching upsert() and query().

Returns one entry per index on the table:

interface LanceIndexCoverage {
  indexName: string
  indexType: string
  columns: string[]
  numIndexedRows: number
  numUnindexedRows: number
}

optimize()

Runs LanceDB table maintenance. It compacts data files, adds rows written since the index was built to the existing index, and removes old table versions. Mastra never calls it automatically. Concurrent calls for the same table in one process share a single run.

tableName?:

string

Table to optimize. Defaults to indexName when omitted.

indexName?:

string

Used as the table name when tableName is omitted.

cleanupOlderThan?:

Date

Remove table versions older than this date. When omitted, LanceDB keeps versions from the last 7 days.

deleteUnverified?:

boolean

= false

Also delete unverified files newer than 7 days. Only set this when no other process writes to the table, or the table can be corrupted.

Returns LanceDB OptimizeStats (compaction and pruning counts).

When to optimize

upsert() writes rows outside the existing vector index. query() still returns those rows by scanning them without the index, so results stay complete, but queries get slower as unindexed rows grow. LanceDB's fastSearch() skips unindexed rows entirely.

optimize() adds new rows to the existing index without retraining it. If your data distribution has changed a lot, rebuild the index with deleteIndex() and createIndex() instead.

LanceDB suggests optimizing after roughly 100,000 modified rows or 20 write operations. Use getIndexCoverage() to build your own policy:

const [coverage] = await store.getIndexCoverage({ indexName: 'docs' })
const total = coverage.numIndexedRows + coverage.numUnindexedRows

if (coverage.numUnindexedRows >= 1_000 && coverage.numUnindexedRows / total >= 0.1) {
  await store.optimize({ indexName: 'docs' })
}

Managed LanceDB Cloud and Enterprise maintain tables automatically, so you don't need to call optimize() there.

deleteIndex()

indexName:

string

Name of the index to delete

updateVector()

Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.

indexName:

string

Name of the index containing the vector

id?:

string

ID of the vector to update (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vector(s) to update (mutually exclusive with id)

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Object containing the vector and/or metadata to update

deleteVector()

indexName:

string

Name of the index containing the vector

id:

string

ID of the vector to delete

deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

indexName:

string

Name of the index containing the vectors to delete

ids?:

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vectors to delete (mutually exclusive with ids)

close()

Closes the database connection.

Response types

Query results are returned in this format:

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
  document?: string // Document text if available
}

Error handling

The store throws typed errors that can be caught:

try {
  await store.query({
    tableName: 'my_vectors',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof Error) {
    console.log(error.message)
  }
}

Best practices

• Use the appropriate index type for your use case:
  • HNSW for better recall and performance when memory isn't constrained
  • IVF for better memory efficiency with large datasets
• For optimal performance with large datasets, consider adjusting numPartitions and numSubVectors values
• Use close() method to properly close connections when done with the database
• Store metadata with a consistent schema to simplify filtering operations

Related

• Metadata Filters