$planCacheStats

項目一覧

定義

Considerations
パイプライン
制限事項
アクセス制御
編集
読み込み設定 (read preference)
出力
例
クエリキャッシュ内のすべてのエントリの情報を返す
クエリハッシュのキャッシュエントリの詳細の検索

定義

$planCacheStats

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

$planCacheStatsステージはパイプラインの最初のステージである必要があります。ステージは空のドキュメントをパラメーターとして受け取り、次の構文を使用します。

{ $planCacheStats: { } }

Tip

以下も参照してください。

クエリプラン

Considerations

パイプライン

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

制限事項

$planCacheStats は、次の場合は許可されません。
- トランザクション
- $facet 集計ステージ
$planCacheStats には読み取り保証（read concern）レベル"local"が必要です。

アクセス制御

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

編集

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

読み込み設定 (read preference)

$planCacheStats は、プランキャッシュ情報を返すホストを選択する際に読み込み設定（ read preference ）を監視します。

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

出力

バージョン 7.0 で変更。

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

1 は、クラシックエンジンが使用されたことを示します。
2 スロットベースのクエリ実行エンジンが使用されたことを示します。

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

{
   "version" : 1,
   "createdFromQuery" : <document>,
   "queryHash" : <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>,
   "host" : <string>,
   "shard" : <string>
}

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

フィールド

説明

version

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

1 は、クラシックエンジンが使用されたことを示します。
2 スロットベースのクエリ実行エンジンが使用されたことを示します。

createdFromQuery

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

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

isActive

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

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

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

queryHash

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

planCacheKey

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

cachedPlan

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

works

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

timeOfCreation

エントリの作成時刻。

creationExecStats

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

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

candidatePlanScores

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

indexFilterSet

クエリシェイプにインデックスフィルターが存在するかどうかを示すブール値。

estimatedSizeBytes

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

host

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

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

shard

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

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

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

{
   "version" : 2,
   "queryHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "isActive" :  <boolean>,
   "works" : <NumberLong>,
   "cachedPlan" : {
      "slots" : <string>,
      "stages": <string>
   },
   "indexFilterSet" : <boolean>,
   "estimatedSizeBytes" : <num>,
   "host" : <string>
}

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

フィールド	説明
`version`	クエリを完了するために使用されたクエリエンジンを示す数値。 `1` は、クラシックエンジンが使用されたことを示します。 `2` スロットベースのクエリ実行エンジンが使用されたことを示します。
`queryHash`	クエリシェイプのハッシュを表す 16進数の string です。詳しくは`explain.queryPlanner.queryHash`を参照してください。
`planCacheKey`	このクエリに関連付けられているプランキャッシュエントリを見つけるために使用されるキーのハッシュを表す 16 進数の string です。プランキャッシュキーは、クエリシェイプとそのシェイプで現在使用可能なインデックスの両方の関数です。 See `explain.queryPlanner.planCacheKey`.
`isActive`	エントリがアクティブか非アクティブかを示すブール値。アクティブな場合、クエリプランナーは現在エントリを使用してクエリプランを生成しています。非アクティブの場合、クエリプランナーは現在、クエリプランを生成するためにエントリを使用していません。「プランキャッシュエントリの状態」を参照してください。
`works`	クエリプランナーが候補プランを評価する試用期間中にクエリ実行プランによって実行された「ワークユニット」の数。詳しくは、 `explain.executionStats.executionStages.works`を参照してください。
`cachedPlan`	キャッシュされたプランの詳細。 `cachedPlan`に含まれるフィールドは、クエリがクラシックエンジンで完了されたか、スロットベースのクエリ実行エンジンで完了されたかによって異なります。クエリプランの詳細については、 `explain.queryPlanner`を参照してください。
`indexFilterSet`	クエリシェイプにインデックスフィルターが存在するかどうかを示すブール値。
`estimatedSizeBytes`	プランキャッシュエントリの推定サイズ（バイト単位）。
`host`	プランキャッシュ情報が返された`mongod`インスタンスのホスト名とポート。シャーディングされたシャーディングされたクラスターで実行すると、操作は各シャードレプリカセット内の 1 つのノードからのプランキャッシュエントリ情報を返します。このメンバーは、シャードフィールドとホストフィールドによって識別されます。「編集」も参照してください。

例

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

db.orders.insertMany( [
   { "_id" : 1, "item" : "abc", "price" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" },
   { "_id" : 2, "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" },
   { "_id" : 3, "item" : "abc", "price" : NumberDecimal("10"), "quantity" : 5, "type": "apparel" },
   { "_id" : 4, "item" : "abc", "price" : NumberDecimal("8"), "quantity" : 10, "type": "apparel" },
   { "_id" : 5, "item" : "jkl", "price" : NumberDecimal("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: NumberDecimal("10")} } }
);

注意

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

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

db.orders.find( { item: "abc", price: { $gte: NumberDecimal("10") } } )
db.orders.find( { item: "abc", price: { $gte: NumberDecimal("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',
    queryHash: '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',
       queryHash: '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',
       queryHash: '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',
       queryHash: '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'
     }
   ],

planCacheKey も参照してください。

クエリハッシュのキャッシュエントリの詳細の検索

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

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

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

出力:

[
  {
    version: '2',
    queryHash: '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'
  }
]

「 planCacheKeyとqueryHashも参照してください。

戻る

$out

$project

定義

Tip