AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。
Docs Menu

MongoDB ベクトル検索結果の説明

explain メソッドを使用してMongoDB ベクトル検索クエリを実行すると、クエリは内部でクエリを実行する方法を説明するクエリプランと実行統計を含むBSONドキュメントを返します。

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 の動作と返される情報の量を制御します。値は、冗長を減らすために、次のいずれかになります。

クエリの実行統計を含む stats フィールドを含むクエリプランに関する情報プラン選択 中にキャプチャされた部分的な実行データが含まれます。

クエリの実行統計情報をもつ stats フィールドを含む、クエリプランに関する情報です。

queryPlanner (デフォルト)

クエリプランに関する情報。stats フィールドは、クエリの実行統計をもつため、含まれていません。

explain メソッドは、次のフィールドを含むBSONドキュメントを返します。

オプション
タイプ
必要性
目的

collectors

ドキュメント

任意

コレクターの実行統計を説明します。

metadata

ドキュメント

任意

有用なメタデータを含んでいます。

query

ドキュメント

任意

クエリの実行統計を説明します。これは indexPartitionExplain のトップ レベルにはありません。

resultMaterialization

ドキュメント

任意

クエリ実行後にドキュメントごとのデータを取得する方法の詳細。これは、queryPlanner の冗長モードでは返されません。

resourceUsage

ドキュメント

任意

クエリが実行されたときのリソース使用状況を詳述します。queryPlannerの冗長モードでは返されません。

vectorTracing

オブジェクトの配列

任意

指定されたドキュメント内のベクトルについて、次のような詳細をトレースします。

  • MongoDB ベクトル検索 がクエリの実行中にベクトルを訪問したかどうか、ベクトルがMongoDB ベクトル検索結果セットにベクトルが表示されたかどうか、およびベクトルが削除された理由は次のとおりです。

  • ベクトルが通常到達可能かどうかは、Hierarchical Navigable Small Worlds の確率的な性質上、一部のベクトルが到達できない可能性があるためです。

luceneVectorSegmentStats

オブジェクトの配列

任意

$vectorSearch クエリ実行の Per Lucene セグメントの詳細。

collectors は、次のフィールドを含むBSONドキュメントです。

フィールド
タイプ
必要性
目的

allCollectorStats

ドキュメント

必須

クエリのすべてのコレクターの統計情報。報告される統計は、クエリで使用されるすべてのコレクターにわたる最大値または、すべてのサブコレクションにわたる統計の合計を表します。タイミング統計は、クエリ全体のすべてのコレクターで費やされた合計時間を反映するように合計されます。詳しくは、 を参照してください。

allCollectorStats は、クエリで指定されたすべてのコレクターのコレクター統計を記述するBSONドキュメントです。これには、次のキーが含まれています。

フィールド
説明

collect

コレクターが収集した期間と結果の数を追跡します。

competitiveIterator

コレクターから competitiveIterator が要求された合計時間と回数を追跡する統計。

setScorer

スコアラーがコレクターに設定された合計時間と回数を追跡する統計。

metadata には、次のような有用なメタデータが含まれています。

フィールド
タイプ
必要性
目的

mongotVersion

文字列

任意

mongotの現在のバージョンです。

mongotHostName

文字列

任意

mongot ホストを識別する、人間が判読できるラベル。

indexName

文字列

任意

クエリで使用されるMongoDB ベクトル検索インデックス。

cursorOptions

ドキュメント

任意

mongot に指定されたカーソル オプション。

totalLuceneDocs

整数

任意

削除されたドキュメントを含むインデックス内のドキュメントの合計数。

explain応答は、クエリの実行統計を説明するキーと値を含むBSONドキュメントです。結果セット内の explainドキュメントには、次のフィールドが含まれています。

フィールド
タイプ
必要性
目的

path

string

任意

クエリされた埋め込みフィールドへのパス(ルートでない場合にのみ)。

type

string

必須

ベクトル検索クエリーのタイプの名前。詳しくは、 query を参照してください。

args

ドキュメント

必須

ベクトル検索クエリー情報。詳しくは、 query を参照してください。

stats

ドキュメント

任意

stats for the query if explain ran with executionStats or allPlansExecution verbosity.

explain 応答には、クエリが内部的に実行された方法に関する情報が含まれます。args フィールドには、次の詳細が含まれています。

  • クエリ タイプ

  • 各クエリ タイプの構造化された概要の例

  • 構造化サマリー内のクエリ オプション

次のセクションでは、クエリのタイプと構造化サマリーのフィールドについて説明します。

WrappedKnnQuery

複数のクエリを組み合わせた Ann ベクトル検索に使用されるラッパークエリ。構造化されたサマリーには、次のオプションの詳細が含まれます。

フィールド
タイプ
必要性
説明

query

配列

必須

ベクトル検索で使用されるサブクエリの配列。通常、KnnFloatVectorQueryDocAndScoreQuery が含まれます。

KnnFloatVectorQuery

浮動小数ベクトルに対する ANN 検索に固有のクエリ タイプ。構造化されたサマリーには、次のオプションに関する詳細が含まれています。

フィールド
タイプ
必要性
説明

field

文字列

必須

検索対象のベクトルフィールドパス。

k

整数

必須

検索する最近傍の数。

DocAndScoreQuery

ドキュメントの一致とスコアリングを処理するクエリタイプ。構造化されたサマリーには通常、クエリの実行に関する統計が含まれます。

ExactVectorSearchQuery

ENNベクトル検索のクエリ タイプ。構造化されたサマリーには、次のオプションに関する詳細が含まれています。

フィールド
タイプ
必要性
説明

field

文字列

必須

検索対象のベクトルフィールドパス。

similarityFunction

文字列

必須

使用される類似性関数(dotProductcosine、または euclidean)。

filter

ドキュメント

任意

ベクトル検索範囲を制限するプレフィルター クエリ。

BooleanQuery

ベクトル検索クエリーで事前フィルターを使用する場合、説明結果にはBooleanQuery 型が含まれます。このタイプのフィールドおよび事前フィルター クエリに固有のその他のクエリ タイプの詳細については、 MongoDB Search 説明ページの「 クエリ タイプ 」を参照してください。

DefaultQuery

別のクエリによって明示的に定義されていないクエリは、デフォルトのクエリを使用して直列化されます。構造化されたサマリーには、次のオプションの詳細が含まれます。

フィールド
タイプ
必要性
説明

queryType

文字列

必須

クエリのタイプ。

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:

フィールド
タイプ
説明

millisElapsed

Long

Approximate wall-clock time elapsed performing tasks in this area including the amount of time the children of the query spent in this area. The value is approximate number of milliseconds elapsed while performing tasks in this area.

invocationCounts

ドキュメント

Number of invocations of tasks included in this area. The value is a map of task names to their invocation count.

統計は、クエリの次の領域で利用できます。

オプション
説明

context

ベクトル検索クエリーの実行に関連する統計。この領域には、呼び出し回数が列挙されるタスクが 2 つあります。

createScorer

スコアリングはドキュメントを反復処理し、各ドキュメントに対してスコアを生成します。 createScorerを呼び出すと、スコアリングを担当するオブジェクトが作成されます。 このタスクに関連付けられている時間は、実際にドキュメントのスコアリングに費やされた時間ではないことに注意してください。 カウントにはscorerSupplier呼び出しの数が含まれます。

createWeight

重みはクエリとIndexSearcherに関連付けられた状態を保存します。 カウントにはcreateWeight呼び出しの数が含まれます。

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.

以下に例を挙げます。

"context" : {
"millisElapsed" : NumberDouble(4.934751),
"invocationCounts" : {
"createWeight" : NumberLong(1),
"createScorer" : NumberLong(10)
}
}

match

結果ドキュメントの反復処理と一致に関連する統計。 この統計は、どのドキュメントが次の一致であるかを決定するのにかかる時間を示しています。 結果のマッチングに費やされる時間は、クエリの性質によって大きく異なる場合があります。 この領域には、呼び出し回数が列挙されるタスクが 2 つあります。

nextDoc

結果セットの次のドキュメントに進むことを要求します。 これには、スキップを識別して過去のスキップに移動するか、次の一致を見つけるために必要なその他のタスクが含まれます。 カウントには、 nextDocadvanceの呼び出しの数が含まれます。

refineRoughMatch

より完全な一致を実行します。 一部のクエリは 2 段階のプロセスで実行されます。このプロセスではドキュメントは最初に「ほぼ」一致し、最初のおおよその一致を満たした後にのみ、2 番目のより詳細なフェーズでチェックされます。 refineRoughMatchタスクは、2 フェーズ プロセスの 2 番目のフェーズです。 カウントにはrefineRoughMatch呼び出しの数が含まれます。

以下に例を挙げます。

"match" : {
"millisElapsed" : NumberDouble(4.901597),
"invocationCounts" : {
"nextDoc" : NumberLong(541),
"refineRoughMatch" : NumberLong(0)
}
}

score

結果セット内のドキュメントのスコアリングに関連する統計。 この領域には、呼び出し回数が列挙されるタスクが 2 つあります。

score

結果セット内の各ドキュメントにスコアを付けます。 カウントにはscore呼び出しの数が含まれます。

setMinCompetitiveScore

指定された値よりスコアが小さいドキュメントを無視します。 スコアが一定の非競合しきい値を下回るドキュメントを無視することで、クエリが実行されるスコアリング操作の数を減らすことができた可能性があることを示します。 カウントにはsetMinCompetitiveScore呼び出しの数が含まれます。

以下に例を挙げます。

"score" : {
"millisElapsed" : NumberDouble(3.931312),
"invocationCounts" : {
"score" : NumberLong(536),
"setMinCompetitiveScore" : NumberLong(0)
}
}

resourceUsage ドキュメントには、クエリの実行に使用されるリソースが表示されます。次のフィールドが含まれています。

フィールド
タイプ
必要性
目的

majorFaults

Long

必須

クエリ実行中にシステムがメモリ内で必要なデータを見つけられず、ディスクなどのバッキング ストアから読み込む場合に発生するメジャーなページ フォールトの数。

minorFaults

Long

必須

データがページキャッシュにあるが、まだプロセスのページテーブルにマップされていない場合に発生するマイナーページフォールトの数。

userTimeMs

Long

必須

ユーザー空間で費やされた CPU 時間(ミリ秒単位)。

systemTimeMs

Long

必須

システム空間で費やされた CPU 時間(ミリ秒単位)。

maxReportingThreads

整数

必須

すべてのバッチでのクエリ実行中にmongotが使用したスレッドの最大数。非並行のExplainクエリの場合、値は1です。

numBatches

整数

必須

クエリのプロセシング中に mongot が要求されたバッチの総数。

vectorTracing 配列にはドキュメントごとに 1 つのオブジェクトのリストが含まれています。これには、ドキュメント内のベクトルに関する次の詳細があります。

フィールド
タイプ
必要性
目的

visited

ブール値

必須

クエリの実行中にトレースされたベクトルが訪問されたかどうかを指定するフラグ。

dropReason

文字列

条件付き

ベクトルを削除する理由。これは、ベクトルが訪問され、結果から削除された場合にのみ存在します。値は次のとおりです。

  • Merge

  • NonCompetitiveScore

  • Filter

  • Rescoring

vectorSearchScore

Double

条件付き

ベクトルに関連付けられたスコア。これはベクトルが訪問された場合にのみ存在します

luceneSegment

整数

必須

ベクトルが属する Lucene セグメント番号。詳しくは、 を参照してください。

unreachable

ブール値

条件付き

ベクトルが到達不能かどうかを指定するフラグ。これはベクトルが到達不能な場合にのみ存在します。

オブジェクトの 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
}
}
フィールド
タイプ
必要性
目的

executionType

文字列

必須

実行戦略。値は次のいずれかになります。

  • Approximate

  • Exact

  • ApproximateToExactFallback

approximateStage

Float

条件付き

近似フェーズの時間(ミリ秒単位)。これは、ApproximateApproximateFallbackToExact 実行タイプでのみ返されます。

exactStage

Float

条件付き

正確なフェーズの時間(ミリ秒単位)。これは、ExactApproximateFallbackToExact 実行タイプでのみ返されます。

filterMatchedDocsCount

整数

任意

クエリでプレフィルターを指定した場合に、クエリフィルターに一致したドキュメントの数。

docCount

整数

必須

セグメント内のドキュメントの合計数。

次の例では、サンプルAnnexplain ENN クエリで メソッドを使用します。自分の環境で次の例を実行するには、まず を使用してMongoDB ベクトル検索クイック mongoshスタートを完了する必要があります。

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
}
}
])

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
}
}
])

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')
]
}
}
}
])