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

# Lance 向量儲存

LanceVectorStore 類別使用 [LanceDB](https://lancedb.github.io/lancedb/) 提供向量搜尋。LanceDB 是建基於 Lance 欄式格式的嵌入式向量資料庫，為本機開發及生產部署提供高效儲存和快速相似度搜尋。

## 工廠方法

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`): 向量維度（必須與你的 embedding 模型相符）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋所用的距離度量 (Default: `cosine`)

**indexConfig** (`LanceIndexConfig`): 索引設定 (Default: `{ type: 'hnsw' }`)

#### `LanceIndexConfig`

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

**type.ivfflat** (`ivfflat`): 將向量分群至多個列表以進行近似搜尋。

**type.hnsw** (`hnsw`): 以圖形為基礎的索引，提供快速搜尋和高召回率。

**numPartitions** (`number`): IVF 索引的分區數量 (Default: `128`)

**numSubVectors** (`number`): 乘積量化的子向量數量 (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 向量的資料表名稱

**vectors** (`number[][]`): embedding 向量陣列

**metadata** (`Record<string, any>[]`): 每個向量的 metadata

**ids** (`string[]`): 選填的向量 ID（如未提供則自動產生）

### `query()`

**tableName** (`string`): 要查詢的資料表名稱

**queryVector** (`number[]`): 查詢向量

**topK** (`number`): 要傳回的結果數量 (Default: `10`)

**filter** (`Record<string, any>`): Metadata 篩選條件

**includeVector** (`boolean`): 是否在結果中包含向量 (Default: `false`)

**columns** (`string[]`): 要在結果中包含的特定欄 (Default: `[]`)

**includeAllColumns** (`boolean`): 是否在結果中包含所有欄 (Default: `false`)

### `listTables()`

傳回由資料表名稱字串組成的陣列。

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

### `getTableSchema()`

**tableName** (`string`): 要描述的資料表名稱

傳回指定資料表的結構描述。

### `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 或 metadata 篩選條件更新單一向量。必須提供 `id` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要更新的向量 ID（與 filter 互斥）

**filter** (`Record<string, any>`): 用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 包含要更新之向量及／或 metadata 的物件

### `deleteVector()`

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要刪除的向量 ID

### `deleteVectors()`

按 ID 或 metadata 篩選條件刪除多個向量。必須提供 `ids` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含該向量的索引名稱s to delete

**ids** (`string[]`): 要刪除的向量 ID 陣列（與 filter 互斥）

**filter** (`Record<string, any>`): 用於識別要刪除向量的 metadata 篩選條件（與 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()` 方法正確關閉連線

- 使用一致的結構描述儲存 metadata，以簡化篩選操作

## 相關內容

- [Metadata 篩選條件](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)