explain メソッドを使用してMongoDB ベクトル検索クエリを実行すると、クエリは内部でクエリを実行する方法を説明するクエリプランと実行統計を含むBSONドキュメントを返します。
Tip
構文
db.<myCollection>.explain("<verbosity>").aggregate([ { "$vectorSearch": { "exact": true | false, "filter": {<filter-specification>}, "index": "<index-name>", "limit": <number-of-results>, "numCandidates": <number-of-candidates>, "path": "<field-to-search>", "queryVector": [<array-of-numbers>], "explainOptions": { "traceDocumentIds": [<array-of-document-IDs>] } } } ])
冗長
冗長モードは、explain の動作と返される情報の量を制御します。値は、冗長を減らすために、次のいずれかになります。
クエリの実行統計を含む | |
クエリの実行統計情報をもつ | |
queryPlanner (デフォルト) | クエリプランに関する情報。 |
Tip
explain の結果
explain メソッドは、次のフィールドを含むBSONドキュメントを返します。
オプション | タイプ | 必要性 | 目的 |
|---|---|---|---|
| ドキュメント | 任意 | コレクターの実行統計を説明します。 |
| ドキュメント | 任意 | 有用なメタデータを含んでいます。 |
| ドキュメント | 任意 | クエリの実行統計を説明します。これは |
| ドキュメント | 任意 | クエリ実行後にドキュメントごとのデータを取得する方法の詳細。これは、 |
| ドキュメント | 任意 | クエリが実行されたときのリソース使用状況を詳述します。 |
| オブジェクトの配列 | 任意 | 指定されたドキュメント内のベクトルについて、次のような詳細をトレースします。
|
| オブジェクトの配列 | 任意 |
|
collectors
collectors は、次のフィールドを含むBSONドキュメントです。
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| ドキュメント | 必須 | クエリのすべてのコレクターの統計情報。報告される統計は、クエリで使用されるすべてのコレクターにわたる最大値または、すべてのサブコレクションにわたる統計の合計を表します。タイミング統計は、クエリ全体のすべてのコレクターで費やされた合計時間を反映するように合計されます。詳しくは |
allCollectorStats
allCollectorStats は、クエリで指定されたすべてのコレクターのコレクター統計を記述するBSONドキュメントです。これには、次のキーが含まれています。
フィールド | 説明 |
|---|---|
| コレクターが収集した期間と結果の数を追跡します。 |
| コレクターから |
| スコアラーがコレクターに設定された合計時間と回数を追跡する統計。 |
metadata
metadata には、次のような有用なメタデータが含まれています。
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| 文字列 | 任意 |
|
| 文字列 | 任意 |
|
| 文字列 | 任意 | クエリで使用されるMongoDB ベクトル検索インデックス。 |
| ドキュメント | 任意 |
|
| 整数 | 任意 | 削除されたドキュメントを含むインデックス内のドキュメントの合計数。 |
query
explain 応答は、クエリの実行統計を記述するキーと値を含む BSON ドキュメントです。結果セットに含まれる explain ドキュメントには、次のフィールドが含まれています。
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| string | 任意 | クエリされた埋め込みフィールドへのパス(ルートでない場合にのみ)。 |
| string | 必須 | ベクトル検索クエリーのタイプの名前。詳しくは、 |
| ドキュメント | 必須 | ベクトル検索クエリー情報。詳しくは、 |
| ドキュメント | 任意 |
|
args
explain 応答には、クエリが内部的に実行された方法に関する情報が含まれます。argsフィールドには、次の詳細が含まれます。
クエリ タイプ
各クエリ タイプの構造化された概要の例
構造化サマリー内のクエリ オプション
次のセクションでは、クエリのタイプと構造化サマリーのフィールドについて説明します。
WrappedKnnQuery複数のクエリを組み合わせた Ann ベクトル検索に使用されるラッパークエリ。構造化されたサマリーには、次のオプションの詳細が含まれます。
フィールドタイプ必要性説明query配列
必須
ベクトル検索で使用されるサブクエリの配列。通常、
KnnFloatVectorQueryとDocAndScoreQueryが含まれます。
KnnFloatVectorQuery浮動小数ベクトルに対する ANN 検索に固有のクエリ タイプ。構造化されたサマリーには、次のオプションに関する詳細が含まれています。
フィールドタイプ必要性説明field文字列
必須
検索対象のベクトルフィールドパス。
k整数
必須
検索する最近傍の数。
ExactVectorSearchQueryENNベクトル検索のクエリ タイプ。構造化されたサマリーには、次のオプションに関する詳細が含まれています。
フィールドタイプ必要性説明field文字列
必須
検索対象のベクトルフィールドパス。
similarityFunction文字列
必須
使用される類似性関数(
dotProduct、cosine、またはeuclidean)。filterドキュメント
任意
ベクトル検索範囲を制限するプレフィルター クエリ。
BooleanQueryベクトル検索クエリーで事前フィルターを使用する場合、説明結果には
BooleanQuery型が含まれます。このタイプのフィールドおよび事前フィルター クエリに固有のその他のクエリ タイプの詳細については、 MongoDB Search 説明ページ の「 クエリ タイプ 」を参照してください。
stats
executionStats と allPlansExecution の冗長モードのexplain レスポンスにはstats 、クエリ実行のさまざまな段階でクエリ に費やされた 時間 に関する情報を含む フィールドが含まれています。
タイミングの内訳
クエリの領域
統計は、クエリの次の領域で利用できます。
オプション | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|
| ベクトル検索クエリーの実行に関連する統計。この領域には、呼び出し回数が列挙されるタスクが 2 つあります。
この領域で費やされる時間はクエリの構造に関連しており、反復処理されスコア付けされる結果の数には基づいていません。 以下に例を挙げます。 | |||||||
| 結果ドキュメントの反復処理と一致に関連する統計。 この統計は、どのドキュメントが次の一致であるかを決定するのにかかる時間を示しています。 結果のマッチングに費やされる時間は、クエリの性質によって大きく異なる場合があります。 この領域には、呼び出し回数が列挙されるタスクが 2 つあります。
以下に例を挙げます。 | |||||||
| 結果セット内のドキュメントのスコアリングに関連する統計。 この領域には、呼び出し回数が列挙されるタスクが 2 つあります。
以下に例を挙げます。 |
resourceUsage
resourceUsage ドキュメントには、クエリの実行に使用されるリソースが表示されます。次のフィールドが含まれています。
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| Long | 必須 | クエリ実行中にシステムがメモリ内で必要なデータを見つけられず、ディスクなどのバッキング ストアから読み込む場合に発生するメジャーなページ フォールトの数。 |
| Long | 必須 | データがページキャッシュにあるが、まだプロセスのページテーブルにマップされていない場合に発生するマイナーページフォールトの数。 |
| Long | 必須 | ユーザー空間で費やされた CPU 時間(ミリ秒単位)。 |
| Long | 必須 | システム空間で費やされた CPU 時間(ミリ秒単位)。 |
| 整数 | 必須 | すべてのバッチでのクエリ実行中に |
| 整数 | 必須 | クエリのプロセシング中に |
vectorTracing
vectorTracing 配列にはドキュメントごとに 1 つのオブジェクトのリストが含まれています。これには、ドキュメント内のベクトルに関する次の詳細があります。
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| ブール値 | 必須 | クエリの実行中にトレースされたベクトルが訪問されたかどうかを指定するフラグ。 |
| 文字列 | 条件付き | ベクトルを削除する理由。これは、ベクトルが訪問され、結果から削除された場合にのみ存在します。値は次のとおりです。
|
| Double | 条件付き | ベクトルに関連付けられたスコア。これはベクトルが訪問された場合にのみ存在します |
| 整数 | 必須 | ベクトルが属する Lucene セグメント番号。詳細については、 |
| ブール値 | 条件付き | ベクトルが到達不能かどうかを指定するフラグ。これはベクトルが到達不能な場合にのみ存在します。 |
luceneVectorSegmentStats
オブジェクトの luceneVectorSegmentStats 配列には、$vectorSearch クエリ実行の Lucene セグメントごとの内訳が含まれています。各セグメントは番号で識別され、クエリ実行の詳細を記述する パラメーターが含まれます。
{ "0": { "executionType": "Approximate", "approximateTimeMillis": 0.10825, "filterMatchedDocsCount": 0, "docCount": 100 }, "1": { "executionType": "Exact", "exactTimeMillis": 0.10825, "filterMatchedDocsCount": 0, "docCount": 55 }, "2": { "executionType": "ApproximateToExactFallback", "approximateTimeMillis": 0.10825, "exactTimeMillis": 0.10825, "filterMatchedDocsCount": 0, "docCount": 55 } }
フィールド | タイプ | 必要性 | 目的 |
|---|---|---|---|
| 文字列 | 必須 | 実行戦略。値は次のいずれかになります。
|
| Float | 条件付き | 近似フェーズの時間(ミリ秒単位)。これは、 |
| Float | 条件付き | 正確なフェーズの時間(ミリ秒単位)。これは、 |
| 整数 | 任意 | クエリでプレフィルターを指定した場合に、クエリフィルターに一致したドキュメントの数。 |
| 整数 | 必須 | セグメント内のドキュメントの合計数。 |
例
以下の例では、explain メソッドを使用して、サンプルの 近似最近傍探索 クエリと 厳密最近傍探索 クエリを実行します。次の例を独自の環境で実行する場合は、まず、. を使用して MongoDB ベクトル検索クイック スタート mongoshを完了する必要があります。
allPlansExecution
以下の例では、 plot_embedding_voyage_3_largeフィールドに対して、allPlansExecution 冗長 モードを使用して、 近似最近傍探索 と 厳密最近傍探索 のベクトル検索クエリに explain メソッドを実行します。
db.embedded_movies.explain("allPlansExecution").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10 } } ])
db.embedded_movies.explain("allPlansExecution").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
queryPlanner
以下の例では、 plot_embedding_voyage_3_largeフィールドに対して、queryPlanner 冗長 モードを使用して、 近似最近傍探索 と 厳密最近傍探索 のベクトル検索クエリに explain メソッドを実行します。
db.embedded_movies.explain("queryPlanner").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10 } } ])
db.embedded_movies.explain("queryPlanner").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
executionStats
以下の例では、 plot_embedding_voyage_3_largeフィールドに対して、executionStats 冗長 モードを使用して、 近似最近傍探索 と 厳密最近傍探索 のベクトル検索クエリに explain メソッドを実行します。
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10, "explainOptions": { "traceDocumentIds": [ ObjectId('573a13d8f29313caabda6557'), ObjectId('573a1398f29313caabce98d9'), ObjectId('573a1391f29313caabcd8319'), ObjectId('573a1398f29313caabceb500'), ObjectId('573a1397f29313caabce780e') ] } } } ])