Plan cache entry lifecycle: Inactive and Active entries and works growth
Parent: Replanning loops and replanReason · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Plan cache entry lifecycle: Inactive and Active entries and works growth. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- In the ordinary non-pinned entry lifecycle, Missing means no cached entry; planning creates an Inactive placeholder recording expected work. An Inactive entry does not supply a reusable execution plan; Active entries do. (medium confidence) [source]
- Pinned entries are an exception to the ordinary lifecycle: r8.0.0 constructs them as Active without a decision-cost value, and they are not subject to performance-triggered replanning. The 2024 engineering issue also distinguishes classic works from SBE reads; inspect the metric type before interpreting a baseline. (medium confidence) [source]
Structure and components
- The work baseline represents engine work, not elapsed milliseconds or a comparison against a freshly measured alternative. Percona publishes a classic-engine log with expected work 2 and observed work at least 20; Alibaba also illustrates replanReason in work units. Such a message alone does not establish a tenfold wall-clock slowdown. (medium confidence) [source]
How it works
- A replan loop can occur with the same query shape and same plan: an expensive parameter value causes deactivation, a cheaper execution reactivates the entry with a lower baseline, and a later expensive execution exceeds that baseline again. SERVER-79039 describes this mechanism; Percona independently documents parameter-dependent repeated replanning. (medium confidence) [source]
- The SERVER-32452 design specifies a default doubling of the inactive works baseline when a new winner exceeds it. MongoDB r8.0.0 implements coefficient-based growth; this baseline growth must be distinguished from the separate degradation threshold that triggers replanning. (medium confidence) [source]
How-to and procedures
- Use normal query executions when testing activation: MongoDB documents that explain ignores existing cache entries and prevents creation of a new cache entry. Percona's suggestion to demonstrate cached-plan reuse with explain should not be treated as proof of reuse. (medium confidence) [source]
Problems, failure modes and limitations
- Use actual query executions and $planCacheStats or PlanCache.list() to inspect lifecycle state and its baseline. explain() bypasses existing cached plans and does not create a cache entry, so repeated explain() calls cannot demonstrate promotion from Inactive to Active. (medium confidence) [source]
Comparisons and alternatives
- In the MongoDB r8.0.0 implementation, an unsuccessful activation raises the baseline to max(old + 1, size_t(old * growthCoefficient)), rather than adopting the latest query cost. The original design documents a default multiplier of two; the +1 floor guarantees progress after rounding. (medium confidence) [source]
- In MongoDB r8.0.0, deactivate() clones the existing entry and changes isActive to false. It preserves the stored readsOrWorks baseline rather than deleting the entry, which limits immediate adoption of an even worse plan. (medium confidence) [source]
Facts and statements
- For a missing ordinary entry, planning creates an inactive placeholder. On a later execution, a winning plan with work no greater than the inactive baseline becomes active; a worse winner leaves it inactive. Activation is therefore conditional, not guaranteed on the second execution. (medium confidence) [source]
- Inactive entries were introduced to prevent an unusually expensive initial plan from installing an excessively permissive baseline that could suppress future replanning. SERVER-32452 records the change in 4.1.1 for the 4.2 production series. (medium confidence) [source]
- Deactivation and cache removal differ. Inactive entries retain a cost baseline, while restart, relevant DDL and LRU eviction can remove entries entirely; LRU removal applies regardless of entry state. (medium confidence) [source]
- The inactive-entry design addressed a historical problem in which a very high initial works baseline could prevent replanning away from a poor cached plan. SERVER-32452 introduced the active/inactive distinction; SERVER-79039 explains that this protection does not eliminate the opposite low-baseline loop. (medium confidence) [source]
- Inspect the cache with $planCacheStats or getPlanCache().list(); an entry's presence alone does not establish active reuse. Percona shows isActive and works in cache output, while MongoDB distinguishes inactive placeholders from usable active entries. (medium confidence) [source]
- The r8.0.0 state machine has explicit exceptions: pinned entries are active and outside normal works-based replanning, and internalQueryCacheDisableInactiveEntries bypasses inactive-entry behavior. The three-state narrative should be scoped to ordinary entries with inactive states enabled. (low confidence) [source]
- The proposal SERVER-106395 to activate plans with similar performance is recorded as Won't Fix with no fix version. Its title is not evidence that MongoDB shipped a tolerance around the ordinary baseline comparison. (low confidence) (verified as of 2025-06-19) [source]
Children
- No children recorded.