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
The explain response for executionStats and allPlansExecution verbosity modes includes a stats field that contains information on how much time a query spends in various stages of query execution.
タイミングの内訳
The timing breakdown describes execution statistics pertinent to an areas of query execution. The following fields show the timing breakdown:
フィールド | タイプ | 説明 |
|---|---|---|
| Long | |
| ドキュメント | Number of invocations of tasks included in this area. The value is a map of task names to their invocation count. |
クエリの領域
統計は、クエリの次の領域で利用できます。
オプション | 説明 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ベクトル検索クエリーの実行に関連する統計。この領域には、呼び出し回数が列挙されるタスクが 2 つあります。
The time spent in this area is related to the structure of the query, and is not based on the number of results that are iterated through and scored. 以下に例を挙げます。 | |||||||||||
| 結果ドキュメントの反復処理と一致に関連する統計。 この統計は、どのドキュメントが次の一致であるかを決定するのにかかる時間を示しています。 結果のマッチングに費やされる時間は、クエリの性質によって大きく異なる場合があります。 この領域には、呼び出し回数が列挙されるタスクが 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 | 条件付き | 正確なフェーズの時間(ミリ秒単位)。これは、 |
| 整数 | 任意 | クエリでプレフィルターを指定した場合に、クエリフィルターに一致したドキュメントの数。 |
| 整数 | 必須 | セグメント内のドキュメントの合計数。 |
例
次の例では、サンプルAnnexplain と ENN クエリで メソッドを使用します。自分の環境で次の例を実行するには、まず を使用してMongoDB ベクトル検索クイック mongoshスタートを完了する必要があります。
allPlansExecution
plot_embedding_voyage_3_large次の例では、allPlansExecution の冗長モードを使用して、 フィールドの DN と ENNベクトル検索クエリーで 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 の冗長モードを使用して、 フィールドの DN と ENNベクトル検索クエリーで 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
The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the executionStats verbosity mode.
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') ] } } } ])