Skip to main content

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