Skip to Content
リファレンスRAGCouchbaseVector

Couchbase Vector Store

CouchbaseVectorクラスはCouchbase Vector Searchを使用してベクトル検索を提供します。Couchbaseコレクション内で効率的な類似性検索とメタデータフィルタリングを可能にします。

要件

  • Couchbase Server 7.6.4+ または互換性のあるCapellaクラスター
  • CouchbaseデプロイメントでSearch Serviceが有効化されていること

インストール

npm install @mastra/couchbase

使用例

import { CouchbaseVector } from '@mastra/couchbase'; const store = new CouchbaseVector({ 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, });

コンストラクタオプション

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'
= cosine
類似性検索のための距離メトリック

upsert()

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

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

indexName:

string
挿入先のインデックス名

vectors:

number[][]
埋め込みベクトルの配列

metadata?:

Record<string, any>[]
各ベクトルのメタデータ

ids?:

string[]
オプションのベクトルID(提供されない場合は自動生成)

query()

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

警告: filterincludeVectorパラメータは現在サポートされていません。フィルタリングは結果を取得した後にクライアント側で実行するか、CouchbaseSDKのSearch機能を直接使用する必要があります。ベクトル埋め込みを取得するには、CouchbaseSDKを使用してIDで完全なドキュメントを取得してください。

indexName:

string
検索対象のインデックス名

queryVector:

number[]
類似ベクトルを見つけるためのクエリベクトル

topK?:

number
= 10
返す結果の数

filter?:

Record<string, any>
メタデータフィルター

includeVector?:

boolean
= false
結果にベクトルデータを含めるかどうか

minScore?:

number
= 0
最小類似性スコアの閾値

describeIndex()

インデックスに関する情報を返します。

indexName:

string
説明するインデックスの名前

戻り値:

interface IndexStats { dimension: number; count: number; metric: "cosine" | "euclidean" | "dotproduct"; }

deleteIndex()

インデックスとそのすべてのデータを削除します。

indexName:

string
削除するインデックスの名前

listIndexes()

Couchbaseバケット内のすべてのベクトルインデックスをリストします。

戻り値: Promise<string[]>

updateVector()

IDによって特定のベクトルエントリを新しいベクトルデータやメタデータで更新します。

indexName:

string
ベクトルを含むインデックスの名前

id:

string
更新するベクトルエントリのID

update:

object
ベクトルやメタデータを含む更新データ

update.vector?:

number[]
更新する新しいベクトルデータ

update.metadata?:

Record<string, any>
更新する新しいメタデータ

deleteVector()

IDによってインデックスから特定のベクトルエントリを削除します。

indexName:

string
ベクトルを含むインデックスの名前

id:

string
削除するベクトルエントリのID

disconnect()

Couchbaseクライアント接続を閉じます。ストアの使用が完了したときに呼び出す必要があります。

レスポンスタイプ

クエリ結果は以下の形式で返されます:

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

エラーハンドリング

ストアは型付きエラーをスローし、それをキャッチできます:

try { await store.query({ indexName: "my_index", queryVector: queryVector, }); } catch (error) { // 特定のエラーケースを処理 if (error.message.includes("Invalid index name")) { console.error( "インデックス名は文字またはアンダースコアで始まり、有効な文字のみを含む必要があります。" ); } else if (error.message.includes("Index not found")) { console.error("指定されたインデックスが存在しません"); } else { console.error("ベクターストアエラー:", error.message); } }

注意事項

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

制限事項

  • インデックス作成の遅延により、作成直後のクエリに影響を与える可能性があります。
  • 取り込み時にベクトル次元の厳密な強制はありません(次元の不一致はクエリ時にエラーになります)。
  • ベクトルの挿入とインデックスの更新は結果整合性です。書き込み直後の強い整合性は保証されません。

関連