Index filters (planCacheSetFilter) deprecation and migration to query settings
Parent: Operation rejection filters · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Index filters (planCacheSetFilter) deprecation and migration to query settings. 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.
Structure and components
- Migration must preserve the operation structure: legacy filters distinguish query, sort, projection and collation, while literal predicate values do not distinguish otherwise matching filter shapes. (high confidence) [source]
How it works
- Index filters last only for the server process and disappear after shutdown; replacing them addresses restart fragility and the difficulty of administering equivalent filters across cluster nodes. (high confidence) [source]
- When an index filter exists for a matching plan cache query shape, MongoDB ignores the application hint(); inspect indexFilterSet in explain output when a hint appears ineffective. (high confidence) [source]
- An index filter limits candidate indexes but can still produce a collection scan. Missing or hidden specified indexes cause collection-scan fallback; Alibaba warns that this can increase CPU and I/O load. (high confidence) [source]
- planCacheClearFilters removes a specific filter when the plan-cache query shape is supplied; omitting that shape clears all index filters on the collection. (low confidence) [source]
- The inspected MongoDB master explain.cpp emits querySettings and sets indexFilterSet to false when nonempty query settings exist, with an explicit comment that query settings have higher priority than a matching index filter. This observation is implementation evidence, not a guarantee for every released version. (low confidence) (verified as of 2026-10-30) [source]
Problems, failure modes and limitations
- MongoDB deprecated index filters starting in version 8.0 and recommends query settings; the official planCacheSetFilter reference continues to document the legacy command, so deprecation alone does not establish removal. (high confidence) (verified as of 2026-10-14) [source]
Comparisons and alternatives
- Treat migration as a targeted operational change: inspect existing indexes and representative query plans, validate the applied settings and winning plan, and avoid indiscriminate pinning. Alibaba recommends improving queries, indexes, and schema rather than relying indefinitely on filters; Tencent describes verification before and after pinning critical queries. (medium confidence) [source]
- Alibaba Cloud’s July 17, 2026 troubleshooting guide demonstrates planCacheSetFilter and planCacheClearFilters and warns that filter references to missing or hidden indexes fall back to collection scans; treat this as service-specific operational guidance rather than proof that the deprecated API is recommended on every current upstream version. (medium confidence) (verified as of 2026-07-17) [source]
Facts and statements
- The replacement addresses deployment scope: query settings apply to a query shape across the cluster and survive shutdown, while legacy filters are difficult to manage across all nodes. (medium confidence) [source]
- For the replacement, use setQuerySettings with a representative command including $db and settings.indexHints containing ns and allowedIndexes; inspect $querySettings and explain().queryPlanner.querySettings, then remove the legacy filter with planCacheClearFilters. This is a synthesis of the documented interfaces, not evidence of automatic conversion. (medium confidence) [source]
Children
- No children recorded.