> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Lance Vector 存储

LanceVectorStore 类使用 [LanceDB](https://lancedb.github.io/lancedb/) 提供 Vector 搜索。LanceDB 是基于 Lance 列式格式构建的嵌入式 Vector 数据库，可为本地开发和生产部署提供高效存储与快速相似度搜索。

## 工厂方法

LanceVectorStore 使用工厂模式创建实例。你应使用静态 `create()` 方法，而不是直接调用构造函数。

**uri** (`string`): LanceDB 数据库路径或云部署的 URI

**options** (`ConnectionOptions`): LanceDB 的其他连接选项

## 构造示例

你可以使用静态 create 方法创建 `LanceVectorStore` 实例：

```ts
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' },
})
```

## 方法

### `createIndex()`

**tableName** (`string`): 要在其中创建索引的表名称

**indexName** (`string`): 要创建的索引名称（列名）

**dimension** (`number`): Vector 维度（必须与嵌入模型匹配）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜索使用的距离度量 (Default: `cosine`)

**indexConfig** (`LanceIndexConfig`): 索引配置 (Default: `{ type: 'hnsw' }`)

#### `LanceIndexConfig`

**type** (`'ivfflat' | 'hnsw'`): 索引类型 (Default: `hnsw`)

**type.ivfflat** (`ivfflat`): 将 Vector 聚类到列表中以进行近似搜索。

**type.hnsw** (`hnsw`): 基于图的索引，可提供快速搜索和高召回率。

**numPartitions** (`number`): IVF 索引的分区数量 (Default: `128`)

**numSubVectors** (`number`): 乘积量化使用的子 Vector 数量 (Default: `16`)

**hnsw** (`HNSWConfig`): HNSW 配置

**hnsw\.m** (`number`): 每个节点的最大连接数（默认值：16）

**hnsw\.efConstruction** (`number`): 构建时复杂度（默认值：100）

### `createTable()`

**tableName** (`string`): 要创建的表名称

**data** (`Record<string, unknown>[] | TableLike`): 表的初始数据

**options** (`Partial<CreateTableOptions>`): 其他表创建选项

### `upsert()`

**tableName** (`string`): 要向其中 upsert Vector 的表名称

**vectors** (`number[][]`): 嵌入 Vector 数组

**metadata** (`Record<string, any>[]`): 每个 Vector 的元数据

**ids** (`string[]`): 可选的 Vector ID（未提供时自动生成）

### `query()`

**tableName** (`string`): 要查询的表名称

**queryVector** (`number[]`): 查询 Vector

**topK** (`number`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 元数据筛选条件

**includeVector** (`boolean`): 结果中是否包含 Vector (Default: `false`)

**columns** (`string[]`): 结果中要包含的指定列 (Default: `[]`)

**includeAllColumns** (`boolean`): 结果中是否包含所有列 (Default: `false`)

### `listTables()`

返回由表名称字符串组成的数组。

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

### `getTableSchema()`

**tableName** (`string`): 要描述的表名称

返回指定表的 schema。

### `deleteTable()`

**tableName** (`string`): 要删除的表名称

### `deleteAllTables()`

删除数据库中的所有表。

### `listIndexes()`

返回由索引名称字符串组成的数组。

### `describeIndex()`

**indexName** (`string`): 要描述的索引名称

返回索引信息：

```typescript
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`): 要删除的索引名称

### `updateVector()`

按 ID 或元数据筛选条件更新单个 Vector。必须提供 `id` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要更新的 Vector ID（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别待更新 Vector 的元数据筛选条件（与 id 互斥）

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 包含待更新 Vector 和/或元数据的对象

### `deleteVector()`

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要删除的 Vector ID

### `deleteVectors()`

按 ID 或元数据筛选条件删除多个 Vector。必须提供 `ids` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含待删除 Vector 的索引名称

**ids** (`string[]`): 要删除的 Vector ID 数组（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别待删除 Vector 的元数据筛选条件（与 ids 互斥）

### `close()`

关闭数据库连接。

## 响应类型

查询结果以以下格式返回：

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

## 错误处理

该存储会抛出可捕获的类型化错误：

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

## 最佳实践

- 根据你的用例选择合适的索引类型：

  - 内存不受限时，使用 HNSW 可获得更好的召回率和性能
  - 对于大型数据集，使用 IVF 可提高内存效率

- 对于大型数据集，可以考虑调整 `numPartitions` 和 `numSubVectors` 的值，以获得最佳性能

- 数据库使用完毕后，使用 `close()` 方法正确关闭连接

- 使用一致的 schema 存储元数据，以简化筛选操作

## 相关内容

- [元数据筛选](https://mastra.zisheng.pro/reference/rag/metadata-filters)