> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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`): 向量維度（必須與嵌入模型相符）

**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[][]`): 嵌入向量陣列

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

**ids** (`string[]`): 選用的向量 ID（未提供時會自動產生）

### `query()`

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

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

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

**filter** (`Record<string, any>`): 中繼資料篩選條件

**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`): 要描述的資料表名稱

傳回指定資料表的 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 或中繼資料篩選條件更新單一向量。必須提供 `id` 或 `filter` 其中一項，但不能同時提供兩者。

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

**id** (`string`): 要更新的向量 ID（不可與 filter 同時使用）

**filter** (`Record<string, any>`): 用於識別待更新向量的中繼資料篩選條件（不可與 id 同時使用）

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

### `deleteVector()`

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

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

### `deleteVectors()`

依 ID 或中繼資料篩選條件刪除多個向量。必須提供 `ids` 或 `filter` 其中一項，但不能同時提供兩者。

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

**ids** (`string[]`): 要刪除的向量 ID 陣列（不可與 filter 同時使用）

**filter** (`Record<string, any>`): 用於識別待刪除向量的中繼資料篩選條件（不可與 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/zh-TW/reference/rag/metadata-filters)