Skip to Content
ReferenceRAGReference: Lance Vector Store | Vector Databases | RAG | Mastra Docs

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' | 'hnsw'
= hnsw
Index type
string

ivfflat:

ivfflat
Clusters vectors into lists for approximate search.

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

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";
  type: "ivfflat" | "hnsw";
  config: {
    m?: number;
    efConstruction?: number;
    numPartitions?: number;
    numSubVectors?: number;
  };
}

deleteIndex()

indexName:

string
Name of the index to delete

updateVector()

indexName:

string
Name of the index containing the vector

id:

string
ID of the vector to update

update:

object
Update parameters
object

vector?:

number[]
New vector values

metadata?:

Record<string, any>
New metadata values

deleteVector()

indexName:

string
Name of the index containing the vector

id:

string
ID of the vector to delete

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
UpstashVectorAnswerRelevancy