Couchbase vector store

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

要件

• Couchbase Server 7.6.4 以降または互換性のある Capella クラスター
• Couchbase デプロイで Search Service が有効であること

インストール

npm

npm install @mastra/couchbase@latest

pnpm

pnpm add @mastra/couchbase@latest

Yarn

yarn add @mastra/couchbase@latest

Bun

bun add @mastra/couchbase@latest

使用例

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'

= 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

= 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 を指定して特定のベクトルエントリを、新しいベクトルデータやメタデータで更新します。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 の使用後に呼び出してください。

レスポンス型

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

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

エラー処理

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

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 組み込みのレプリケーション機能と永続化機能の使用を検討してください。効率的な検索を維持するため、インデックス統計を定期的に監視してください。

制限事項

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

関連情報

• メタデータフィルター