- Reference >
- Operators >
- Aggregation Pipeline Stages >
- $planCacheStats
$planCacheStats¶
On this page
Definition¶
-
$planCacheStats
¶ New in version 4.2.
Returns plan cache information for a collection. The stage returns a document for each plan cache entry.
The
$planCacheStats
stage must be the first stage in the pipeline. The stage takes an empty document as a parameter and has the following syntax:Note
The
$planCacheStats
aggregation stage is preferred over the following methods and commands, which have been deprecated in 4.2:PlanCache.getPlansByQuery()
method/planCacheListPlans
command, andPlanCache.listQueryShapes()
method/planCacheListQueryShapes
command.
See also
Considerations¶
Pipeline¶
$planCacheStats
must be the first stage in an aggregation
pipeline.
Restrictions¶
$planCacheStats
is not allowed in:- transactions
$facet
aggregation stage
$planCacheStats
requires read concern levellocal
.$planCacheStats
cannot be run onmongos
instances.
Access Control¶
On systems running with authorization
, the user
must have the planCacheRead
privilege for the collection.
Output¶
For each plan cache entry, the $planCacheStats
stage returns a
document similar to the following:
Each document includes various query plan and execution stats, including:
Field | Description |
---|---|
createdFromQuery |
A document that contains the specific query that resulted in this cache entry; i.e. |
isActive |
A boolean that indicates whether the entry is active or inactive.
See also |
queryHash |
A hexadecimal string that represents the hash of the query
shape. For more information, see
explain.queryPlanner.queryHash |
planCacheKey |
A hexadecimal string that represents the hash of the key used to
find the plan cache entry associated with this query. The plan
cache key is a function of both the query shape and the
currently available indexes for that shape. For more information, see
explain.queryPlanner.planCacheKey |
cachedPlan | The details of the cached plan. See |
works |
The number of “work units” performed by the query execution plan
during the trial period when the query planner evaluates
candidate plans. For more information, see
explain.executionStats.executionStages.works |
timeOfCreation |
Time of creation for the entry. |
creationExecStats | An array of execution stats documents. The array contains a document for each candidate plan. For details on the execution stats, see
|
candidatePlanScores | An array of scores for the candidate plans listed in the
|
indexFilterSet |
A boolean that indicates whether the an index filter exists for the query shape. |
estimatedSizeBytes |
A number that describes the estimated size in bytes of a plan cache entry. New in version 4.2.12. |
Examples¶
The examples in this section use the following orders
collection:
Create the following indexes on the collection:
Note
Index { item: 1, price: 1 }
is a partial index and only indexes documents with price
field greater than or equal to NumberDecimal("10")
.
Run some queries against the collection:
Return Information for All Entries in the Query Cache¶
The following aggregation pipeline uses $planCacheStats
to
return information on the plan cache entries for the collection:
The operation returns all entries in the cache:
See also planCacheKey.
List Query Shapes¶
Like the planCacheListQueryShapes
command, the
$planCacheStats
stage can be used to obtain a list of all
of the query shapes for which there is a cached plan. The
$planCacheStats
aggregation stage is preferred over the
deprecated PlanCache.listQueryShapes()
method and the
deprecated planCacheListQueryShapes
command.
For example, the following uses the $project
stage to only
output the createdFromQuery
field and the queryHash
field.
The operation returns the following query shapes:
Find Cache Entry Details for a Query Shape¶
To return plan cache information for a particular query shape, the
$planCacheStats
stage can be followed by a
$match
on the planCacheKey
field.
The following aggregation pipeline uses $planCacheStats
followed by a $match
and $project
to return
specific information for a particular query shape:
The operation returns the following:
See also planCacheKey and queryHash.