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

# Couchbase 向量儲存

`CouchbaseVector` 類別使用 [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html) 提供向量搜尋功能，讓你可以在 Couchbase collection 內高效執行相似度搜尋及 metadata 篩選。

## 系統要求

- **Couchbase Server 7.6.4+** 或兼容的 Capella cluster
- Couchbase 部署已啟用 **Search Service**

## 安裝

**npm**:

```bash
npm install @mastra/couchbase@latest
```

**pnpm**:

```bash
pnpm add @mastra/couchbase@latest
```

**Yarn**:

```bash
yarn add @mastra/couchbase@latest
```

**Bun**:

```bash
bun add @mastra/couchbase@latest
```

## 使用範例

```typescript
import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})
```

## 建構函數選項

**id** (`string`): 此向量儲存 instance 的唯一識別碼

**connectionString** (`string`): Couchbase 連線字串

**username** (`string`): Couchbase 使用者名稱

**password** (`string`): Couchbase 密碼

**bucketName** (`string`): 要使用的 Couchbase bucket 名稱

**scopeName** (`string`): 要使用的 Couchbase scope 名稱

**collectionName** (`string`): 要使用的 Couchbase collection 名稱

**options** (`CouchbaseClientOptions`): 可選的 Couchbase client 選項

## 方法

### `createIndex()`

在 Couchbase 中建立新的向量索引。

> **備註:** 索引建立程序以非同步方式進行。呼叫 `createIndex` 後，請先等候一段時間（小型資料集通常需時 1 至 5 秒，大型資料集則需要更長時間）才執行查詢。在正式環境中，應實作輪詢來檢查索引狀態，而非使用固定延遲。

**indexName** (`string`): 要建立的索引名稱

**dimension** (`number`): 向量維度（必須與你的 embedding model 相符）

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

### `upsert()`

在 collection 中新增或更新向量及其 metadata。

> **備註:** 你可以在建立索引之前或之後 upsert 資料。`upsert` 方法不要求索引已存在。Couchbase 允許在同一個 collection 上建立多個 Search 索引。

**indexName** (`string`): 要插入資料的索引名稱

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

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

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

### `query()`

搜尋相似向量。

> **注意:** 目前尚未支援 `filter` 及 `includeVector` 參數。擷取結果後，必須在用戶端執行篩選，或直接使用 Couchbase SDK 的 Search 功能。要擷取向量 embedding，請使用 Couchbase SDK 按 ID 取得完整文件。

**indexName** (`string`): 要搜尋的索引名稱

**queryVector** (`number[]`): 用來尋找相似向量的查詢向量

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

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

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

**minScore** (`number`): 最低相似度分數門檻 (Default: `0`)

### `describeIndex()`

傳回索引的相關資訊。

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

傳回：

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}
```

### `deleteIndex()`

刪除索引及其所有資料。

**indexName** (`string`): 要刪除的索引名稱

### `listIndexes()`

列出 Couchbase bucket 中的所有向量索引。

傳回：`Promise<string[]>`

### `updateVector()`

按 ID 使用新的向量資料及／或 metadata 更新指定的向量項目。Couchbase 尚未實作按 filter 更新的功能。

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

**id** (`string`): 要更新的向量項目 ID

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

### `deleteVector()`

按 ID 從索引刪除單一向量。

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

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

### `deleteVectors()`

按 ID 刪除多個向量。Couchbase 尚未實作按 filter 刪除的功能。

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

**ids** (`string[]`): 要刪除的向量 ID 陣列

### `disconnect()`

關閉 Couchbase client 連線。使用完此 store 後應呼叫此方法。

## 回應類型

查詢結果會以以下格式傳回：

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

## 錯誤處理

此向量儲存會拋出可捕捉的具類型錯誤：

```typescript
try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}
```

## 注意事項

- **刪除索引的注意事項：** 刪除 Search 索引不會刪除相關 Couchbase collection 中的向量／文件。除非明確移除，否則資料會繼續保留。
- **所需權限：** Couchbase 使用者必須擁有連線、讀取／寫入目標 collection 中文件（`kv` 角色），以及管理 Search 索引（相關 bucket／scope 上的 `search_admin` 角色）的權限。
- **索引定義詳情及文件結構：** `createIndex` 方法會建立 Search 索引定義，為 `embedding` 欄位（類型為 `vector`）及 `content` 欄位（類型為 `text`）建立索引，並以指定 `scopeName.collectionName` 內的文件為目標。每份文件會將向量儲存在 `embedding` 欄位，並將 metadata 儲存在 `metadata` 欄位。如果 `metadata` 包含 `text` 屬性，其值亦會複製至頂層的 `content` 欄位，以供文字搜尋建立索引。
- **複寫及耐久性：** 請考慮使用 Couchbase 內置的複寫及持久化功能來確保資料耐久性。請定期監察索引統計資料，以維持高效搜尋。

## 限制

- 建立索引的延遲可能會影響建立後立即執行的查詢。
- 匯入資料時不會強制檢查向量維度（維度不相符會在查詢時引發錯誤）。
- 向量插入及索引更新採用最終一致性。寫入後無法保證立即達到強一致性。

## 相關內容

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