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,
});

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

メソッド

createIndex()

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

注意: インデックス作成は非同期です。createIndexを呼び出した後、クエリを実行する前に時間を置いてください（小さなデータセットでは通常1〜5秒、大きなデータセットではより長時間）。本番環境では、固定の遅延を使用するのではなく、インデックスのステータスをチェックするポーリングを実装してください。

upsert()

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

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

query()

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

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

describeIndex()

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

戻り値:

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

deleteIndex()

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

listIndexes()

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

戻り値: Promise<string[]>

updateVector()

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

deleteVector()

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フィールドにメタデータを格納します。metadataにtextプロパティが含まれている場合、その値はトップレベルのcontentフィールドにもコピーされ、テキスト検索用にインデックス化されます。
• レプリケーションと耐久性: データの耐久性のために、Couchbaseの組み込みレプリケーションと永続化機能の使用を検討してください。効率的な検索を確保するため、インデックス統計を定期的に監視してください。

制限事項

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

関連

• メタデータフィルター