MongoDB $planCacheStats Stage

Example 1 — Sample Data

Three orders, an index on status, then warm the plan cache with two different query shapes.

db.orders.drop()
db.orders.insertMany([
  { status: "active", total: 40 },
  { status: "active", total: 15 },
  { status: "closed", total: 99 }
])

db.orders.createIndex({ status: 1 })

// Warm the plan cache (planner may store a plan per shape)
db.orders.find({ status: "active" }).toArray()
db.orders.find({ status: "closed" }).toArray()

How the Data Is Stored in MongoDB

Confirm the documents with a simple read:

db.orders.find().sort({ status: 1, total: 1 })

{ status: "active", total: 15 }
{ status: "active", total: 40 }
{ status: "closed", total: 99 }

Read the important pieces like this:

How It Works

1. Seed data. Three orders give the planner something to scan.
2. Add an index. createIndex({ status: 1 }) changes plan choices.
3. Warm the cache. Each distinct find() shape can create a cache entry.
4. Next examples. $planCacheStats lists those entries—not the order rows.

Example 2 — List Cache

Goal: after Example 1, list every cached plan for orders.

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

{
  planCacheKey: "...",
  planCacheShapeHash: "...",
  isActive: true,
  works: 12,
  cachedPlan: { /* stage tree */ }
}
// Exact field names vary slightly by MongoDB version
// Empty [] if Example 1 warm-up was skipped

How It Works

1. First stage. Empty {} must lead the pipeline on orders.
2. One doc per entry. Each row is a cached plan, not an order document.
3. Needs warm-up. Run Example 1 first or you may get an empty result.
4. Live metadata. Output reflects your server’s plan cache right now.

Example 3 — Clean Report

Goal: after Example 1, keep only the fields you need and sort by trial cost (works).

db.orders.aggregate([
  { $planCacheStats: {} },
  {
    $project: {
      planCacheKey: 1,
      planCacheShapeHash: 1,
      isActive: 1,
      works: 1,
      _id: 0
    }
  },
  { $sort: { works: -1 } },
  { $limit: 10 }
])

Highest works floats to the top
Review those shapes with explain()
Keep reports short with $limit

How It Works

1. List first. Stage 1 still emits full cache documents.
2. Project. Drop bulky plan trees for a quick audit.
3. Sort. Highest works first = focus candidates.
4. Limit. Cap the report so dashboards stay small.

Example 4 — Filter Active

Goal: after Example 1, keep only active cache entries, then peek at the chosen stage type.

db.orders.aggregate([
  { $planCacheStats: {} },
  { $match: { isActive: true } },
  {
    $project: {
      planCacheKey: 1,
      works: 1,
      stage: "$cachedPlan.stage",
      _id: 0
    }
  }
])

// Tip: clear cache in mongosh when testing plan changes:
// db.orders.getPlanCache().clear()

{
  planCacheKey: "...",
  works: 12,
  stage: "IXSCAN"
}
// stage path may nest deeper depending on version/plan shape

How It Works

1. Match after. Filter cache docs with isActive: true.
2. Project stage. Surface whether the plan looks like IXSCAN.
3. Tune loop. Pair with explain() on the real query.
4. Clear when testing. getPlanCache().clear() resets entries.