Attribute pattern and wildcardProjection design
Parent: MongoDB Wildcard and Hidden Indexes, Index Builds and Index Overhead · Published reference · snapshot 2026-10-21 · skill ranked-1cb7f7b2
↓ Facts as markdownall context files
Source-anchored research for Attribute pattern and wildcardProjection design. 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
- The Attribute Pattern is a schema transformation: move a subset of related or rare and unpredictable fields into an array or subdocument of key/value-like entries, optionally with qualifiers, then index those repeated paths. MongoDB's examples say this can reduce the need for separate indexes across variable field names. (high confidence) [source]
How it works
- A path-scoped wildcard term such as `customFields.$**` is a separate option for indexing a known subtree without a projection. MongoDB permits `wildcardProjection` only when the wildcard term is exactly `$**`; to filter the indexed paths, use `$**` with a projection. A compound wildcard index can pair ordinary fields with `$**` and a projection. (high confidence) [source]
- Spring Data MongoDB has an integration-level constraint: its reference shows `wildcardProjection` on a root `@WildcardIndexed` type and says the option is not allowed on nested property paths. The current index resolver raises a `MappingException` when a nested property annotation includes a projection. This describes Spring Data mapping behavior, not a MongoDB server rule. (medium confidence) (verified as of 2026-10-21) [source]
- A broad wildcard index can grow with the number of scalar paths in nested documents and arrays, increasing disk and memory use. Percona recommends monitoring index size and using projections or targeted indexes when only a stable subset of fields is queried. (high confidence) [source]
How-to and procedures
- Use wildcard indexes when field names are unknown or may change. MongoDB says wildcard indexes do not perform as well as targeted indexes on known paths and recommends remodeling toward consistent field names when possible. Percona also warns that broad wildcard indexes can become bottlenecks, recommends monitoring index size, and suggests excluding fields that do not need coverage. (high confidence) [source]
- Use wildcard indexes when field paths are unknown or may change. MongoDB says targeted indexes on known fields perform better and suggests remodeling arbitrary field names into consistent paths when possible; Percona also recommends targeted index types for stable workloads. (high confidence) [source]
Problems, failure modes and limitations
- wildcardProjection has design constraints: the index key must use $**, and the projection cannot mix inclusion and exclusion rules except for _id. A field-scoped wildcard key such as userMetadata.$** cannot use wildcardProjection. (high confidence) [source]
- Spring Data MongoDB 5.1.1 skips Map-like properties during index resolution unless they use @WildcardIndexed, because dynamic map keys cannot be resolved from static mapping metadata. Its wildcardProjection setting is supported on a root entity type annotation, not on a nested property annotation. (low confidence) (verified as of 2026-10-21) [source]
Facts and statements
- `wildcardProjection` controls indexed path coverage without changing the document schema. With a global `$**` wildcard term, an inclusion projection indexes the selected dotted paths and recurses into embedded documents or arrays to index scalar descendants; an exclusion projection omits the selected paths. The projection must use inclusion or exclusion consistently, except for `_id`. Wildcard indexes omit `_id` unless the projection explicitly includes it. (high confidence) [source]
- MongoDB's wildcard restrictions page reports stricter validation for new compound wildcard `wildcardProjection` definitions starting in MongoDB 8.3, 8.2.4, 8.0.18, and 7.0.29; existing indexes that do not meet the new rules continue to function. Check the deployed patch version before creating compound wildcard indexes with a projection. (low confidence) (verified as of 2026-10-14) [source]
- A wildcardProjection on a $** index can include selected dotted paths with value 1 or exclude them with value 0. MongoDB recursively indexes scalar values in included embedded documents and arrays; a path omitted from the projection is not covered by that wildcard index. (high confidence) [source]
Children
- No children recorded.