MongoDB vector store
MongoDBVector クラスは、MongoDB Atlas Vector Search を使用したベクトル検索を提供します。MongoDB コレクション内で効率的な類似度検索とメタデータフィルタリングを利用できます。
インストールインストールへの直接リンク
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/mongodb@latest
pnpm add @mastra/mongodb@latest
yarn add @mastra/mongodb@latest
bun add @mastra/mongodb@latest
使用例使用例への直接リンク
import { MongoDBVector } from '@mastra/mongodb'
const store = new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI,
dbName: process.env.MONGODB_DB_NAME,
})
埋め込みフィールドのパスをカスタマイズする埋め込みフィールドのパスをカスタマイズするへの直接リンク
埋め込みをネストされたフィールド構造に保存する必要がある場合（既存の MongoDB コレクションとの統合など）は、embeddingFieldPath オプションを使用します。
import { MongoDBVector } from '@mastra/mongodb'
const store = new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI,
dbName: process.env.MONGODB_DB_NAME,
embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
})
コンストラクターオプションコンストラクターオプションへの直接リンク
id:
uri:
dbName:
options?:
embeddingFieldPath?:
メソッドメソッドへの直接リンク
connect()connectへの直接リンク
MongoDB サーバーへの接続を確立します。初回使用時に自動で呼び出されますが、必要に応じて明示的に呼び出すこともできます。
await store.connect()
createIndex()createindexへの直接リンク
MongoDB に新しいベクトルインデックス（コレクション）を作成します。
indexName:
dimension:
metric?:
filterFields?:
metadata.<field> として登録）。宣言済みフィールドだけを使用するクエリは、候補 _id の事前フィルタリングを行わず $vectorSearch に直接プッシュされるため、大規模な結果セットでの 16 MB BSON 制限を回避できます。未宣言フィールドを参照するフィルターや、$vectorSearch が対応していない演算子を使用するフィルターは、自動的に事前フィルターへフォールバックします。collectionName?:
indexName です。searchIndexName?:
${indexName}_vector_index です。allowWrites?:
upsert、updateVector、deleteVector、deleteVectors）をオプトインで有効にします。BYO インデックスはデフォルトで読み取り専用であり、store が呼び出し元所有の運用ドキュメントを変更または削除することはありません。常に書き込み可能な管理対象コレクションでは無視されます。このポリシーはインデックス登録とともに永続化され、再起動後も維持されます。waitForIndexReady()waitforindexreadyへの直接リンク
作成後のインデックスが準備完了になるまで待機します。操作の実行前にインデックスの準備完了を確実にしたい場合に便利です。
indexName:
timeoutMs?:
checkIntervalMs?:
upsert()upsertへの直接リンク
コレクション内のベクトルとメタデータを追加または更新します。BYO コレクションはデフォルトで読み取り専用のため、持ち込みインデックスでは createIndex() の実行時に allowWrites: true を指定する必要があります。
indexName:
vectors:
metadata?:
ids?:
documents?:
query()queryへの直接リンク
省略可能なメタデータフィルタリングを使用して類似ベクトルを検索します。
indexName:
queryVector:
topK?:
filter?:
metadata フィールドに適用）documentFilter?:
includeVector?:
numCandidates?:
metadataMode?:
'field'（デフォルト）は管理対象の metadata / document フィールドを射影し、filter フィールドを metadata サブドキュメントと照合します。'document' はソースドキュメント全体を metadata として返し、filter フィールドを **root** ドキュメントと照合します（metadata. プレフィックスなし）。独自の構造を持つ運用コレクションの持ち込みに使用します。ペイロードの肥大化を避けるため、埋め込みフィールドはデフォルトで metadata から除外されます。保持して metadata に含め、トップレベルの vector としても公開するには includeVector: true を指定します。createSearchIndex()createsearchindexへの直接リンク
インデックスを支えるコレクションに Atlas Search（BM25/全文検索）インデックスをプロビジョニングし、textQuery() と hybridQuery() が対象とするテキスト検索インデックスとして記録します。
管理対象コレクションと持ち込みコレクション:
- 管理対象インデックス（
collectionNameなしで作成）では、createIndex()がすべての文字列フィールドを対象とする${collectionName}_search_indexという名前の dynamic 全文インデックスを作成します。そのためcreateSearchIndex()が必要なのは、フィールドを限定したマッピングまたはカスタムインデックス名を使用する場合だけです。 - 持ち込みインデックス（
collectionNameを指定して作成）では、createIndex()は全文インデックスを自動作成しません。呼び出し元が所有する運用コレクションでのtextQuery()/hybridQuery()はオプトインです。createSearchIndex()を明示的に呼び出し、課金対象のテキストインデックスをプロビジョニングしてください。それまでは、textQuery()/hybridQuery()は存在しないインデックスをクエリせず、明確なエラーをスローします。
命名規則:
fieldsを指定し、searchIndexNameを明示しない場合、フィールドマッピング済みインデックスは論理インデックスごとに一意な別個のデフォルト名（${collectionName}_${indexName}_search_fields_index）で作成されます。管理対象コレクションで自動作成される dynamic インデックスとの衝突によって無視されることを防ぎます。このインデックスはテキスト検索インデックスとして永続化されるため、textQuery()/hybridQuery()は制限されたマッピングを自動的に使用します。searchIndexNameを指定すると、その名前がそのまま使用、永続化されます。textQuery()/hybridQuery()は永続化された名前を自動的に解決します。各呼び出しのsearchIndexName/textSearchIndexNameパラメーターで名前を上書きすることもできます。
indexName:
fields?:
searchIndexName?:
fields を指定してこれを省略すると、論理インデックスごとに一意な別個のデフォルト名が使用されます。これにより、自動作成された dynamic インデックスがフィールドマッピングを隠すことや、同じコレクション上の2つの論理インデックスが衝突することを防ぎます。waitUntilReady?:
waitForSearchIndexReady() を明示的に呼び出します。await store.createSearchIndex({
indexName: 'precedents',
fields: ['note', 'description'],
})
フィールドマッピング済みインデックス名には論理 indexName が含まれるため、同じコレクション上の2つの論理インデックスには別々のテキストインデックスが割り当てられます。同じ論理インデックスを異なる fields で再作成する場合は、先に既存のインデックスを削除する必要があります（IndexAlreadyExists）。
waitForSearchIndexReady()waitforsearchindexreadyへの直接リンク
インデックスの全文検索（BM25）インデックスが READY になるまで待機します。waitForIndexReady() がポーリングするのは vectorSearch インデックスだけです。createSearchIndex() は Atlas Search 全文インデックスの構築中に戻るため、直後の textQuery() / hybridQuery() は断続的に失敗することがあります。このメソッドを呼び出すか、createSearchIndex() に waitUntilReady: true を渡すと、解決されたテキストインデックスが READY になるまで待機します。
indexName:
searchIndexName?:
timeoutMs?:
checkIntervalMs?:
await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
await store.waitForSearchIndexReady({ indexName: 'precedents' })
textQuery()textqueryへの直接リンク
Atlas Search インデックスに対して全文検索（BM25）を実行します。デフォルトでは、このインデックス用に記録されたテキスト検索インデックス（createSearchIndex() で設定、または createIndex() が自動作成する dynamic ${collectionName}_search_index）を対象とします。この呼び出しで特定のインデックスを対象にするには searchIndexName を渡します。
ここでのメタデータフィルターは、hybridQuery() と同様に $match ステージで適用されます。hybridQuery() のベクトル分岐では、インデックス作成時に filterFields で宣言されていないフィールドのフィルターが、query() と同じフォールバックによって候補 _id として透過的に具体化されるため、未宣言フィールドのフィルターでもエラーになりません。
indexName:
query:
paths:
topK?:
filter?:
metadata フィールドに適用）metadataMode?:
'field'（デフォルト）は管理対象の metadata / document フィールドを射影します。'document' はソースドキュメント全体を metadata として返します。searchIndexName?:
createSearchIndex() / createIndex() によって永続化されたインデックスです。const results = await store.textQuery({
indexName: 'precedents',
query: 'shell company offshore',
paths: ['note'],
topK: 10,
})
hybridQuery()hybridqueryへの直接リンク
MongoDB のサーバー側 $rankFusion を使用して、ベクトル類似度と全文検索の結果を融合するハイブリッド検索を実行します。MongoDB 8.0 以降が必要で、8.1 以降では一般提供されています。8.0.x では有効化に MongoDB サポートへの依頼が必要な場合があり、Atlas 8.0.x など有効化された環境で動作します。全文検索インデックスが必要です。管理対象インデックスでは自動作成されますが、持ち込みコレクションでは先に createSearchIndex() を呼び出してオプトインする必要があります。
indexName:
queryVector:
query:
paths:
topK?:
filter?:
weights?:
numCandidates?:
metadataMode?:
'field'（デフォルト）は管理対象の metadata / document フィールドを射影します。'document' はソースドキュメント全体を metadata として返します。textSearchIndexName?:
createSearchIndex() / createIndex() によって永続化されたインデックスです。const results = await store.hybridQuery({
indexName: 'precedents',
queryVector: embedding,
query: 'shell company offshore',
paths: ['note'],
topK: 10,
weights: { vector: 1, text: 1.5 }, // Favor text matches
})
hybridQuery() の $rankFusion ステージには MongoDB 8.0 以降が必要です。このステージは 8.1 以降で一般提供されています。8.0.x では有効化に MongoDB サポートへの依頼が必要な場合があり、Atlas 8.0.x など有効化された環境で動作します。古いバージョンを使用している場合、または 8.0.x 環境で $rankFusion が有効でない場合は、query() と textQuery() を個別に使用し、クライアント側で結果をマージしてください。
describeIndex()describeindexへの直接リンク
インデックス（コレクション）の情報を返します。
indexName:
戻り値:
interface IndexStats {
dimension: number
count: number
metric: 'cosine' | 'euclidean' | 'dotproduct'
}
deleteIndex()deleteindexへの直接リンク
ベクトルインデックスを削除します。動作はインデックスの作成方法によって異なります。
- 管理対象インデックス（
collectionNameなしで作成）: コレクション全体とそのすべてのデータを削除します。 - 持ち込みインデックス（
collectionNameを指定して作成）: Atlas vectorSearch インデックスと、createSearchIndex()で作成されている場合は対応する全文検索インデックスを削除します。呼び出し元の運用コレクションとドキュメントは保持されます。この store が、自身で作成していないコレクションを削除することはありません。
BYO の分類はインデックス作成時に永続的に記録されるため、別のプロセスでも正しく適用されます（セットアップジョブで作成したインデックスを、後で長時間稼働するサービスが削除する場合など）。物理コレクション名ではなく、必ず論理インデックス名（createIndex で使用した indexName）を渡してください。
indexName:
listIndexes()listindexesへの直接リンク
物理コレクション名ではなく、Mastra の論理インデックス名（createIndex に渡した indexName）を一覧表示します。運用コレクションにデータを保存する持ち込みインデックスでは、物理コレクション名ではなく論理インデックス名が返されます。この値はそのまま deleteIndex() / describeIndex() に渡せます。永続メタデータの導入前に作成された管理対象インデックスも、${name}_vector_index 検索インデックスを通じて検出されます。内部レジストリコレクションは一覧に含まれません。
戻り値: Promise<string[]>
updateVector()updatevectorへの直接リンク
ID またはメタデータフィルターで単一のベクトルを更新します。id と filter のいずれか一方だけを指定する必要があります。
持ち込みコレクションはデフォルトで読み取り専用です。 BYO インデックスを
allowWrites: trueで作成していない場合、upsert()、updateVector()、deleteVector()、deleteVectors()は USER カテゴリーのエラーをスローします。既存コレクションのインデックス作成を参照してください。
indexName:
id?:
filter?:
update:
update.vector?:
update.metadata?:
deleteVector()deletevectorへの直接リンク
ID を指定して、インデックスから特定のベクトルエントリを削除します。
indexName:
id:
deleteVectors()deletevectorsへの直接リンク
ID またはメタデータフィルターで複数のベクトルを削除します。ids と filter のいずれか一方だけを指定する必要があります。
indexName:
ids?:
filter?:
disconnect()disconnectへの直接リンク
MongoDB クライアント接続を閉じます。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_collection',
queryVector: queryVector,
})
} catch (error) {
// Handle specific error cases
if (error.message.includes('Invalid collection name')) {
console.error(
'Collection name must start with a letter or underscore and contain only valid characters.',
)
} else if (error.message.includes('Collection not found')) {
console.error('The specified collection does not exist')
} else {
console.error('Vector store error:', error.message)
}
}
既存コレクションのインデックス作成既存コレクションのインデックス作成への直接リンク
管理対象コレクションを使用せず、既存の運用コレクションにベクトルインデックスを作成できます。MongoDB データベースにすでに存在するドキュメントへベクトル検索機能を追加する場合に便利です。
import { MongoDBVector } from '@mastra/mongodb'
const store = new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI,
dbName: process.env.MONGODB_DB_NAME,
})
// Create a vector index on an existing 'transactions' collection
await store.createIndex({
indexName: 'precedents',
dimension: 1024,
collectionName: 'transactions', // Use existing collection
searchIndexName: 'txn_vec_idx', // Custom search index name
})
// Wait for the index to be ready
await store.waitForIndexReady({ indexName: 'precedents' })
// Query using document mode to get full source documents
const hits = await store.query({
indexName: 'precedents',
queryVector: embeddings,
topK: 5,
metadataMode: 'document', // Returns full document as metadata
})
// hits[0].metadata now contains all fields from the source document
console.log(hits[0].metadata.amount, hits[0].metadata.customField)
// Full-text / hybrid search on a BYO collection is opt-in: provision the text index first.
await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
重要な注意事項:
- コレクションはすでに存在し、
embeddingフィールド（または設定したカスタムembeddingFieldPath）を持つドキュメントを含んでいる必要があります collectionNameを使用する場合、コレクションが作成または削除されることはありません- BYO インデックスはデフォルトで読み取り専用です。
upsert()、updateVector()、deleteVector()、deleteVectors()は、呼び出し元所有の運用ドキュメントを変更せず、明確なエラーをスローします。store にコレクションへの埋め込みの書き込みやドキュメントの削除を許可するには、createIndex({ ..., allowWrites: true })で明示的にオプトインします。ポリシーは永続化され、再起動後も維持されます。このフラグなしで古いバージョンが書き込んだエントリは読み取り専用として扱われます（fail closed） - クエリでソースドキュメント全体を
metadataとして取得するにはmetadataMode: 'document'を使用します 'document'モードでは、埋め込みはデフォルトでmetadataから除外されます。保持してトップレベルのvectorとしても公開するにはincludeVector: trueを渡します'document'モードのフィルタリングは root ドキュメントフィールドに作用し、ネストされたmetadata.サブドキュメントには作用しません。filter: { lane: 'fraud' }は運用ドキュメントのトップレベルlaneフィールドと一致します（デフォルトの'field'モードでは、管理対象コレクションの修飾されていないフィールドはmetadata.<field>に書き換えられます）。pushdown と$matchのフォールバック経路の両方でこの動作が維持されます- ネイティブの
ObjectId_idに対応しています。 運用コレクションでは一般にObjectIdをキーとして使用します。クエリ結果は_idを文字列（QueryResult.idの契約）に変換し、deleteVector()/updateVector()/deleteVectors()はその文字列を受け取り、基になるObjectIdドキュメントと照合します。管理対象コレクション（文字列_id）には影響しません - BYO コレクションでの全文検索とハイブリッド検索はオプトインです。全文インデックスは自動作成されないため、
textQuery()/hybridQuery()の前にcreateSearchIndex()を呼び出します。全文インデックスは非同期で構築されます。直後にテキスト検索またはハイブリッド検索を行う場合は、waitForSearchIndexReady()を呼び出すかwaitUntilReady: trueを渡します - BYO インデックスに対する
deleteIndex()はベクトルインデックス（作成されている場合はテキストインデックスも）を削除しますが、コレクションとドキュメントは保持します
ベストプラクティスベストプラクティスへの直接リンク
- クエリ性能を最適化するため、フィルターで使用するメタデータフィールドにインデックスを作成します。
- 予期しないクエリ結果を避けるため、メタデータでは一貫したフィールド名を使用します。
- 効率的な検索を維持するため、インデックスとコレクションの統計を定期的に監視します。
- 既存のコレクションにインデックスを作成する場合は、すべてのドキュメントに必須の
embeddingフィールドがあることを確認します。
使用例使用例への直接リンク
MongoDB によるベクトル埋め込みvector-embeddings-with-mongodbへの直接リンク
埋め込みは、Memory の semanticRecall がキーワードではなく意味に基づいて関連メッセージを取得するために使用する数値ベクトルです。
本番環境では MongoDB Atlas Vector Search を推奨します。セルフホスト環境では、Atlas CLI によるローカル Atlas デプロイで Vector Search を利用できます。
この設定では、ローカル埋め込みモデル FastEmbed を使用して埋め込みベクトルを生成します。
使用するには @mastra/fastembed をインストールします。
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/fastembed@latest
pnpm add @mastra/fastembed@latest
yarn add @mastra/fastembed@latest
bun add @mastra/fastembed@latest
Agent に次の内容を追加します。
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { fastembed } from '@mastra/fastembed'
export const mongodbAgent = new Agent({
id: 'mongodb-agent',
name: 'mongodb-agent',
instructions:
'You are an AI agent with the ability to automatically recall memories from previous interactions.',
model: 'openai/gpt-5.6-sol',
memory: new Memory({
storage: new MongoDBStore({
id: 'mongodb-storage',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
vector: new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
embedder: fastembed,
options: {
lastMessages: 10,
semanticRecall: {
topK: 3,
messageRange: 2,
},
generateTitle: true, // generates descriptive thread titles automatically
},
}),
})
VoyageAI によるベクトル埋め込みVoyageAI によるベクトル埋め込みへの直接リンク
VoyageAI は検索タスク向けに最適化された専用の埋め込みモデルを提供します。また、マルチモーダル埋め込み向けに MongoDB Atlas と統合されています。
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/voyageai@latest
pnpm add @mastra/voyageai@latest
yarn add @mastra/voyageai@latest
bun add @mastra/voyageai@latest
基本的な使用例:
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { voyage } from '@mastra/voyageai'
export const mongodbVoyageAgent = new Agent({
id: 'mongodb-voyage-agent',
name: 'MongoDB VoyageAI Agent',
instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
model: 'openai/gpt-5.6-sol',
memory: new Memory({
storage: new MongoDBStore({
id: 'mongodb-storage',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
vector: new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
embedder: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
options: {
lastMessages: 10,
semanticRecall: {
topK: 5,
messageRange: 2,
},
},
}),
})
専用モデル、マルチモーダル埋め込み、検索最適化を含む VoyageAI 埋め込みの詳細な例については、VoyageAI 埋め込みのドキュメントを参照してください。