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

$planCacheStats

$planCacheStats

コレクションのプラン キャッシュ情報を返します。 ステージでは、プラン キャッシュのエントリごとにドキュメントが返されます。

$planCacheStatsステージはパイプラインの最初のステージである必要があります。ステージの構文は次のとおりです。

{ $planCacheStats: { allHosts: <boolean> }}

$planCacheStats集計ステージには次のオプションがあります。

オプション
説明

allHosts

$planCacheStats集計ステージがシャーディングされたクラスター内のノードを対象とする方法を構成します。

  • trueの場合、 mongosは、ターゲット コレクションからの 1 つ以上のチャンクを含む影響を受けるシャードごとに、 $planCacheStats集計ステージをすべてのノード(プライマリとセカンダリ)にブロードキャストします。

  • falseの場合、 $planCacheStats集計ステージは読み込み設定(read preference) に従い、対象のレプリカセット プライマリからプラン キャッシュのみを検索します。

allHostsがtrueに設定されている場合、レプリカセットとスタンドアロン サーバーはパイプライン解析中にエラーを返します。 オプションは シャーディングされたクラスター でのみ使用できます。

デフォルト: false

バージョン7.1の新機能。

$planCacheStats は、集計パイプラインの最初のステージである必要があります。

authorizationで実行されているシステムでは、ユーザーはコレクションに対するplanCacheRead特権を持っている必要があります。

Queryable Encryptionを使用する場合、操作は通常どおりキャッシュされていれも、 $planCacheStatsステージは暗号化されたコレクションに対する操作を省略します。

allHostsオプションがfalseに設定されている場合、 $planCacheStatsは 読み込み設定( read preference ) に従って、プラン キャッシュ情報を返すホストを選択します。

アプリケーションは、レプリカセットの異なるノードを対象とする場合があります。 そのため、各レプリカセット ノードは異なる読み取りコマンドを受け取り、他のノードとは異なるプラン キャッシュ情報を持っている可能性があります。 ただし、レプリカセットまたはシャーディングされたクラスターで$planCacheStatsを実行すると、通常の読み込み設定(read preference)ルールに従います。 つまり、レプリカセットでは、この操作はレプリカセットの 1 つのメンバーのみからプラン キャッシュ情報を収集し、シャーディングされたクラスターでは、この操作は各シャード レプリカセットの 1 つのメンバーのみからプラン キャッシュ情報を収集します。

バージョン7.0で変更。

$planCacheStatsの出力は、クエリを完了するために使用されるクエリ エンジンによって異なります。 $planCacheStatsのversionフィールドの値は、使用されたクエリ エンジンを示します。

クラシック実行エンジンを使用するクエリの場合、 $planCacheStatsは次のようなドキュメントを返します。

{ "version" : 1, "createdFromQuery" : <document>, "planCacheShapeHash" : <hexadecimal string>, "planCacheKey" : <hexadecimal string>, "isActive" : <boolean>, "works" : <NumberLong>, "cachedPlan" : { "stage" : <STAGE1>, "filter" : <document>, "inputStage" : { "stage" : <STAGE2>, ... } }, "timeOfCreation" : <date>, "creationExecStats" : [ // Exec Stats Document for each candidate plan { "nReturned" : <num>, "executionTimeMillisEstimate" : <num>, "totalKeysExamined" : <num>, "totalDocsExamined" :<num>, "executionStages" : { "stage" : <STAGE A>, ... "inputStage" : { "stage" : <STAGE B>, ... } } }, ... ], "candidatePlanScores" : [ <number>, ... ], "indexFilterSet" : <boolean>, "estimatedSizeBytes" : <num>, "querySettings" : <document>, "host" : <string>, "shard" : <string>}

各ドキュメントには、次のようなさまざまなクエリプランと実行に関する統計が含まれています。

フィールド
説明

version

クエリを完了するために使用されたクエリ エンジンを示す数値。

createdFromQuery

このキャッシュ エントリを生成した特定のクエリを含むドキュメント。 例:

{ "query" : <document>, "sort" : <document>, "projection" : <document>}

isActive

エントリがアクティブか非アクティブかを示すブール値。

  • アクティブな場合、クエリ プランナーは現在 エントリを使用してクエリプランを生成しています。

  • 非アクティブの場合、クエリ プランナーは現在、クエリプランを生成するためにエントリを使用していません。

「プラン キャッシュ エントリの状態 」を参照してください。

planCacheShapeHash

クエリシェイプのハッシュを表す 16進数の string です。 詳しくはexplain.queryPlanner.planCacheShapeHashを参照してください。

MongoDB 8.0 以降では、既存の queryHashフィールドはplanCacheShapeHash という名前の新しいフィールドに重複します。 以前のバージョンのMongoDBを使用している場合は、queryHashフィールドのみが表示されます。 今後のMongoDBバージョンでは、非推奨の queryHashフィールドが排除されます。代わりに planCacheShapeHashフィールドを使用する必要があります。

planCacheKey

このクエリに関連付けられているプラキャッシュエントリを見つけるために使用されるキーのハッシュを表す 16 進数のstringです。 プランキャッシュキーは、プランキャッシュクエリシェイプとそのシェイプで現在使用可能なインデックスの両方の関数です。 詳しくはexplain.queryPlanner.planCacheKeyを参照してください。

cachedPlan

キャッシュされたプランの詳細。 cachedPlanに含まれるフィールドは、クエリがクラシック エンジンで完了されたか、スロットベースのクエリ実行エンジンで完了されたかによって異なります。 クエリプランの詳細については、 explain.queryPlannerを参照してください。

works

クエリ プランナーが候補プランを評価する試用期間中にクエリ実行プランによって実行された「ワーク ユニット」の数。 詳しくは、 explain.executionStats.executionStages.worksを参照してください。

timeOfCreation

エントリの作成時刻。

creationExecStats

実行統計ドキュメントの配列。 配列には、候補プランごとに のドキュメントが含まれています。

実行統計の詳細については、 explain.executionStatsを参照してください。

candidatePlanScores

creationExecStats配列にリストされている候補プランのスコアの配列。

indexFilterSet

estimatedSizeBytes

プラン キャッシュ エントリの推定サイズ(バイト単位)。

querySettings

バージョン8.0の新機能。

以前にsetQuerySettingsを使用して設定されたクエリ設定を含むドキュメント:

querySettings: { indexHints: [ { ns: { db: <string>, coll: <string> }, allowedIndexes: <array> }, ... ], queryFramework: <string>}

querySettings フィールド:

  • indexHints.ns (ドキュメント):インデックスヒントの名前空間。

    • db (string): インデックスヒントのデータベース名。

    • coll (string): インデックスヒントに使用するコレクションの名前。

  • indexHints.allowedIndexes (配列):インデックスヒントのインデックスの配列。詳細については、「インデックス」およびhint()を参照してください。

  • queryFramework (string): クエリフレームワーク string は次のいずれかです。

host

プラン キャッシュ情報が返されたmongodインスタンスのホスト名とポート。

シャーディングされたクラスターで実行すると、操作は各シャード レプリカセット内の 1 つのノードからのプラン キャッシュ エントリ情報を返します。 このメンバーは、シャードフィールドとホストフィールドによって識別されます。 「リダクション 」も参照してください。

shard

$planCacheStatsがキャッシュ エントリを取得したシャードの名前。

シャーディングされたクラスターで実行した場合にのみ使用できます。

このセクションの例では、次の orders コレクションを使用します。

db.orders.insertMany( [ { "_id" : 1, "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type": "apparel" }, { "_id" : 2, "item" : "jkl", "price" : Decimal128("20"), "quantity" : 1, "type": "electronics" }, { "_id" : 3, "item" : "abc", "price" : Decimal128("10"), "quantity" : 5, "type": "apparel" }, { "_id" : 4, "item" : "abc", "price" : Decimal128("8"), "quantity" : 10, "type": "apparel" }, { "_id" : 5, "item" : "jkl", "price" : Decimal128("15"), "quantity" : 15, "type": "electronics" }] )

コレクションに次のインデックスを作成します。

db.orders.createIndex( { item: 1 } );db.orders.createIndex( { item: 1, quantity: 1 } );db.orders.createIndex( { quantity: 1 } );db.orders.createIndex( { quantity: 1, type: 1 } );db.orders.createIndex( { item: 1, price: 1 }, { partialFilterExpression: { price: { $gte: Decimal128("10")} } });

注意

インデックス{ item: 1, price: 1 }は部分インデックスであり、 priceフィールドがDecimal128("10")以上のドキュメントのみをインデックス化します。

コレクションに対していくつかのクエリを実行します。

db.orders.find( { item: "abc", price: { $gte: Decimal128("10") } } )db.orders.find( { item: "abc", price: { $gte: Decimal128("5") } } )db.orders.find( { quantity: { $gte: 20 } } )db.orders.find( { quantity: { $gte: 5 }, type: "apparel" } )

上記のクエリは、スロットベースのクエリ実行エンジンを使用して完了されます。

次の集計パイプラインは$planCacheStats を使用して、コレクションのプランキャッシュエントリに関する情報を返します。

db.orders.aggregate( [ { $planCacheStats: { } }] )

出力:

[ { // Plan Cache Entry 1 version: '2', planCacheShapeHash: '478AD696', planCacheKey: '21AE23AD', isActive: true, works: Long("7"), timeOfCreation: ISODate("2023-05-22T20:33:49.031Z"), cachedPlan: { ... }, indexFilterSet: false, isPinned: false, estimatedSizeBytes: Long("8194"), host: 'mongodb1.example.net:27018' }, { // Plan Cache Entry 2 version: '2', planCacheShapeHash: '3D8AFDC6', planCacheKey: '1C2C4360', isActive: true, works: Long("6"), timeOfCreation: ISODate("2023-05-22T20:33:50.584Z"), cachedPlan: { ... }, indexFilterSet: false, isPinned: false, estimatedSizeBytes: Long("11547"), host: 'mongodb1.example.net:27018' }, { // Plan Cache Entry 3 version: '2', planCacheShapeHash: '27285F9B', planCacheKey: '20BB9404', isActive: true, works: Long("1"), timeOfCreation: ISODate("2023-05-22T20:33:49.051Z"), cachedPlan: { ... }, indexFilterSet: false, isPinned: false, estimatedSizeBytes: Long("7406"), host: 'mongodb1.example.net:27018' }, { // Plan Cache Entry 4 version: '2', planCacheShapeHash: '478AD696', planCacheKey: 'B1435201', isActive: true, works: Long("5"), timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"), cachedPlan: { ... }, indexFilterSet: false, isPinned: false, estimatedSizeBytes: Long("7415"), host: 'mongodb1.example.net:27018' } ],

警告

MongoDB 8.0 以降では、既存の queryHashフィールドはplanCacheShapeHash という名前の新しいフィールドに重複します。 以前のバージョンのMongoDBを使用している場合は、queryHashフィールドのみが表示されます。 今後のMongoDBバージョンでは、非推奨の queryHashフィールドが排除されます。代わりに planCacheShapeHashフィールドを使用する必要があります。

planCacheKey も参照してください。

特定のクエリ ハッシュのプラン キャッシュ情報を返すには、 $planCacheStatsステージの後にplanCacheKeyフィールドの$matchが続くようにします。

次の集計パイプラインでは、 $planCacheStatsとそれに続く$matchステージを使用して、特定のクエリ ハッシュの特定の情報を返しています。

db.orders.aggregate( [ { $planCacheStats: { } }, { $match: { planCacheKey: "B1435201"} }] )

出力:

[ { version: '2', planCacheShapeHash: '478AD696', planCacheKey: 'B1435201', isActive: true, works: Long("5"), timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"), cachedPlan: { slots: '$$RESULT=s11 env: { s3 = 1684787629009 (NOW), s6 = Nothing, s5 = Nothing, s1 = TimeZoneDatabase(Asia/Kuwait...Etc/UCT) (timeZoneDB), s10 = {"item" : 1, "price" : 1}, s2 = Nothing (SEARCH_META) }', stages: '[2] nlj inner [] [s4, s7, s8, s9, s10] \n' + ' left \n' + ' [1] cfilter {(exists(s5) && exists(s6))} \n' + ' [1] ixseek s5 s6 s9 s4 s7 s8 [] @"358822b7-c129-47b7-ad7f-40017a51b03c" @"item_1_price_1" true \n' + ' right \n' + ' [2] limit 1 \n' + ' [2] seek s4 s11 s12 s7 s8 s9 s10 none none [] @"358822b7-c129-47b7-ad7f-40017a51b03c" true false \n' }, indexFilterSet: false, isPinned: false, estimatedSizeBytes: Long("7415"), host: 'mongodb1.example.net:27018' }]

警告

MongoDB 8.0 以降では、既存の queryHashフィールドはplanCacheShapeHash という名前の新しいフィールドに重複します。 以前のバージョンのMongoDBを使用している場合は、queryHashフィールドのみが表示されます。 今後のMongoDBバージョンでは、非推奨の queryHashフィールドが排除されます。代わりに planCacheShapeHashフィールドを使用する必要があります。

詳しくは、 planCacheKeyおよびplanCacheShapeHash も参照してください。