$planCacheStats

項目一覧

定義

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

定義

$planCacheStats

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

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

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

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

オプション

説明

allHosts

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

trueの場合、 mongosは、ターゲットコレクションからの 1 つ以上のチャンクを含む影響を受けるシャードごとに、 $planCacheStats集計ステージをすべてのノード（プライマリとセカンダリ）にブロードキャストします。
falseの場合、 $planCacheStats集計ステージは読み込み設定（read preference）に従い、対象のレプリカセットプライマリからプランキャッシュのみを検索します。

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

デフォルト: false

バージョン 7.1 で追加。

Tip

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

クエリプラン

Considerations

パイプライン

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

制限事項

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

アクセス制御

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

編集

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

読み込み設定 (read preference)

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

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

出力

バージョン 7.0 で変更。

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

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

クラシック実行エンジンを使用するクエリの場合、 $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

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

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

createdFromQuery

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

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

isActive

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

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

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

planCacheShapeHash

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

MongoDB 8.0以降、既存のqueryHashフィールドの名前がplanCacheShapeHashに変更されます。以前のバージョンの MongoDB を使用している場合は、 planCacheShapeHashではなくqueryHashが表示されます。

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は次のとおりです。

classic クラシックエンジン。
sbe スロットベースのクエリ実行エンジン。詳細については、「スロットベースのクエリ実行エンジン」を参照してください。

host

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

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

shard

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

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

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

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

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

フィールド

説明

version

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

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

planCacheShapeHash

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

planCacheKey

isActive

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

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

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

works

cachedPlan

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は次のとおりです。

classic クラシックエンジン。
sbe スロットベースのクエリ実行エンジン。詳細については、「スロットベースのクエリ実行エンジン」を参照してください。

host

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

例

このセクションの例では、次の 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',
    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'
     }
   ],

警告

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

警告

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

戻る

$out

$project

定義

Tip

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

Considerations

パイプライン

制限事項

アクセス制御

編集

読み込み設定 (read preference)

出力

例

注意

クエリ キャッシュ内のすべてのエントリの情報を返す

警告

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

警告

クエリキャッシュ内のすべてのエントリの情報を返す

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