Lance 向量存储

🌐 Lance Vector Store

LanceVectorStore 类使用 LanceDB 提供向量搜索，LanceDB 是基于 Lance 列式格式构建的嵌入式向量数据库。它为本地开发和生产部署提供高效的存储和快速的相似性搜索。

🌐 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

LanceVectorStore 使用工厂模式进行创建。你应该使用静态的 create() 方法，而不是直接使用构造函数。

🌐 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

你可以使用静态的 create 方法来创建一个 LanceVectorStore 实例：

🌐 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()

通过 ID 或元数据过滤器更新单个向量。必须提供 id 或 filter 中的一个，但不能同时提供两者。

🌐 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()

通过 ID 或元数据过滤器删除多个向量。必须提供 ids 或 filter 中的一个，但不能同时提供两者。

🌐 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

• 针对你的使用情况使用合适的索引类型：
  • 当内存不受限制时，HNSW 可实现更好的召回率和性能
  • 使用 IVF 提高大数据集的内存效率
• 为了在处理大型数据集时达到最佳性能，请考虑调整 numPartitions 和 numSubVectors 的数值
• 完成数据库操作后，使用 close() 方法正确关闭连接
• 使用一致的模式存储元数据以简化筛选操作

相关

🌐 Related

• 元数据过滤器