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

# Couchbase Vector 存储

`CouchbaseVector` 类使用 [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html) 提供 Vector 搜索。它可以在 Couchbase collection 中执行高效的相似度搜索和元数据过滤。

## 要求

- **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`): 此 Vector 存储实例的唯一标识符

**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 中创建新的 Vector 索引。

> **备注:** 索引创建是异步的。调用 `createIndex` 后，请等待一段时间再查询（小型数据集通常需要 1 到 5 秒，大型数据集需要更长时间）。在生产环境中，应通过轮询检查索引状态，而不是使用固定延迟。

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

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

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

### `upsert()`

在 collection 中添加或更新 Vector 及其元数据。

> **备注:** 你可以在创建索引之前或之后执行数据 upsert。`upsert` 方法不要求索引已经存在。Couchbase 允许对同一个 collection 创建多个 Search 索引。

**indexName** (`string`): 要插入数据的索引名称

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

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

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

### `query()`

搜索相似 Vector。

> **注意:** 目前不支持 `filter` 和 `includeVector` 参数。必须在检索结果后进行客户端过滤，或者直接使用 Couchbase SDK 的 Search 功能。要检索 Vector embedding，请使用 Couchbase SDK 按 ID 获取完整文档。

**indexName** (`string`): 要在其中搜索的索引名称

**queryVector** (`number[]`): 用于查找相似 Vector 的查询 Vector

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

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

**includeVector** (`boolean`): 是否在结果中包含 Vector 数据 (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 中的所有 Vector 索引。

返回：`Promise<string[]>`

### `updateVector()`

根据 ID 使用新的 Vector 数据和/或元数据更新特定 Vector 条目。Couchbase 尚未实现基于过滤条件的更新。

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

**id** (`string`): 要更新的 Vector 条目 ID

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

### `deleteVector()`

根据 ID 从索引中删除单个 Vector。

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

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

### `deleteVectors()`

根据 ID 删除多个 Vector。Couchbase 尚未实现基于过滤条件的删除。

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

**ids** (`string[]`): 要删除的 Vector ID 数组

### `disconnect()`

关闭 Couchbase client 连接。使用完该存储后应调用此方法。

## 响应类型

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

```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 中的 Vector/文档。除非明确删除，否则数据仍会保留。
- **所需权限：** Couchbase 用户必须具有连接权限、对目标 collection 中的文档进行读写的权限（`kv` role），以及管理 Search 索引的权限（相关 bucket/scope 上的 `search_admin` role）。
- **索引定义详情和文档结构：** `createIndex` 方法会构建一个 Search 索引定义，以索引 `embedding` 字段（类型为 `vector`）和 `content` 字段（类型为 `text`），目标是指定 `scopeName.collectionName` 中的文档。每个文档都将 Vector 存储在 `embedding` 字段中，并将元数据存储在 `metadata` 字段中。如果 `metadata` 包含 `text` 属性，其值还会复制到顶层 `content` 字段，并为文本搜索建立索引。
- **复制和持久性：** 考虑使用 Couchbase 内置的复制和持久化功能来确保持久存储数据。定期监控索引统计信息，以确保搜索高效运行。

## 限制

- 索引创建延迟可能会影响创建后立即执行的查询。
- 写入时不会强制检查 Vector 维度（维度不匹配会在查询时引发错误）。
- Vector 插入和索引更新采用最终一致性。写入后不会立即保证强一致性。

## 相关内容

- [元数据过滤器](https://mastra.zisheng.pro/reference/rag/metadata-filters)