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

# Couchbase vector store

`CouchbaseVector` クラスは、[Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html) を使用したベクトル検索を提供します。Couchbase コレクション内で効率的な類似度検索とメタデータフィルタリングを実行できます。

## 要件

- **Couchbase Server 7.6.4 以降**または互換性のある Capella クラスター
- 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 store インスタンスの一意の識別子

**connectionString** (`string`): Couchbase 接続文字列

**username** (`string`): Couchbase ユーザー名

**password** (`string`): Couchbase パスワード

**bucketName** (`string`): 使用する Couchbase バケットの名前

**scopeName** (`string`): 使用する Couchbase スコープの名前

**collectionName** (`string`): 使用する Couchbase コレクションの名前

**options** (`CouchbaseClientOptions`): 省略可能な Couchbase クライアントオプション

## メソッド

### `createIndex()`

Couchbase に新しいベクトルインデックスを作成します。

> **注記:** インデックスの作成は非同期です。`createIndex` を呼び出した後、クエリを実行するまで時間を置いてください。通常、小規模なデータセットでは 1〜5 秒、大規模なデータセットではさらに長くかかります。本番環境では固定の遅延ではなく、インデックスの状態を確認するポーリングを実装してください。

**indexName** (`string`): 作成するインデックスの名前

**dimension** (`number`): ベクトルの次元数（埋め込みモデルと一致させる必要があります）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 類似度検索の距離指標 (Default: `cosine`)

### `upsert()`

コレクション内のベクトルとそのメタデータを追加または更新します。

> **注記:** インデックスの作成前でも作成後でも、データを upsert できます。`upsert` メソッドではインデックスが存在する必要はありません。Couchbase では同じコレクションに複数の Search インデックスを作成できます。

**indexName** (`string`): 挿入先のインデックス名

**vectors** (`number[][]`): 埋め込みベクトルの配列

**metadata** (`Record<string, any>[]`): 各ベクトルのメタデータ

**ids** (`string[]`): 省略可能なベクトル ID（未指定の場合は自動生成されます）

### `query()`

類似するベクトルを検索します。

> **警告:** 現在、`filter` と `includeVector` パラメーターには対応していません。結果を取得した後にクライアント側でフィルタリングするか、Couchbase SDK の Search 機能を直接使用する必要があります。ベクトル埋め込みを取得するには、Couchbase SDK で ID を指定してドキュメント全体を取得してください。

**indexName** (`string`): 検索対象のインデックス名

**queryVector** (`number[]`): 類似ベクトルを検索するクエリベクトル

**topK** (`number`): 返す結果の数 (Default: `10`)

**filter** (`Record<string, any>`): メタデータフィルター

**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 バケット内のすべてのベクトルインデックスを一覧表示します。

戻り値: `Promise<string[]>`

### `updateVector()`

ID を指定して特定のベクトルエントリを、新しいベクトルデータやメタデータで更新します。Couchbase ではフィルターベースの更新はまだ実装されていません。

**indexName** (`string`): ベクトルを含むインデックスの名前

**id** (`string`): 更新するベクトルエントリの ID

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 更新するベクトルやメタデータを含むオブジェクト

### `deleteVector()`

ID を指定してインデックスから単一のベクトルを削除します。

**indexName** (`string`): ベクトルを含むインデックスの名前

**id** (`string`): 削除するベクトルの ID

### `deleteVectors()`

ID を指定して複数のベクトルを削除します。Couchbase ではフィルターベースの削除はまだ実装されていません。

**indexName** (`string`): ベクトルを含むインデックスの名前

**ids** (`string[]`): 削除するベクトル ID の配列

### `disconnect()`

Couchbase クライアント接続を閉じます。store の使用後に呼び出してください。

## レスポンス型

クエリ結果は次の形式で返されます。

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

## エラー処理

store は捕捉可能な型付きエラーをスローします。

```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 コレクション内のベクトルやドキュメントは削除されません。明示的に削除しない限り、データは残ります。
- **必要な権限:** Couchbase ユーザーには、接続、対象コレクション内のドキュメントの読み書き（`kv` ロール）、Search インデックスの管理（関連するバケットやスコープの `search_admin` ロール）に必要な権限が必要です。
- **インデックス定義とドキュメント構造の詳細:** `createIndex` メソッドは、指定された `scopeName.collectionName` 内のドキュメントを対象に、`embedding` フィールドを `vector` 型、`content` フィールドを `text` 型としてインデックス化する Search インデックス定義を構築します。各ドキュメントは、ベクトルを `embedding` フィールドに、メタデータを `metadata` フィールドに保存します。`metadata` に `text` プロパティが含まれる場合、その値は全文検索用にインデックス化されるトップレベルの `content` フィールドにもコピーされます。
- **レプリケーションと耐久性:** データの耐久性を確保するため、Couchbase 組み込みのレプリケーション機能と永続化機能の使用を検討してください。効率的な検索を維持するため、インデックス統計を定期的に監視してください。

## 制限事項

- インデックス作成の遅延により、作成直後のクエリに影響することがあります。
- 取り込み時にベクトルの次元数は厳密に検証されません。次元数が一致しない場合はクエリ時にエラーになります。
- ベクトルの挿入とインデックスの更新は結果整合性に基づきます。書き込み直後の強い整合性は保証されません。

## 関連情報

- [メタデータフィルター](https://mastra.zisheng.pro/ja/reference/rag/metadata-filters)