Time series bucketing parameters: granularity, bucketMaxSpanSeconds, bucketRoundingSeconds
Parent: Bucket catalog memory and closure reasons · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-2d50f9ab0851
↓ Facts as markdownall context files
Source-anchored research for Time series bucketing parameters: granularity, bucketMaxSpanSeconds, bucketRoundingSeconds. 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.
How it works
- In MongoDB 7.1 and later, fixed-bucket query optimizations require a collection created with both custom parameters and no later parameter changes. For eligible predicates using $gte and $lt on the timeField, MongoDB can omit the per-measurement event filter when the query bounds align with bucket boundaries. (medium confidence) (verified as of 2026-10-22) [source]
Measurements and reference values
- The time-span setting is only one bucket constraint. MongoDB documents a maximum of 1,000 measurements or 125 KB per bucket, whichever is lower, so a configured maximum time span does not guarantee that a bucket remains open for that entire interval. (high confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- During insertion, the BucketCatalog closes an open bucket if the incoming measurement would make the time between the bucket's oldest and newest timestamps exceed the collection's allowed span. A bucket closed for this reason remains eligible for reopening. bucketRoundingSeconds positions a new bucket's lower time boundary; it is not the span limit. (high confidence) [source]
- After collection creation, collMod can increase granularity or the custom span and rounding values but cannot decrease them. Existing bucket documents are not rewritten when the setting changes; the new span applies to new buckets. (high confidence) (verified as of 2026-10-22) [source]
- An October 2023 forum report describes MongoDB 7.0.2 rejecting a 300-second custom pair after an upgrade from 6.0.3 with the error that bucketMaxSpanSeconds was not configurable away from the default 3,600 for the provided granularity. A MongoDB respondent attributed the failure to an incomplete upgrade and advised following the release procedure; this is version-specific troubleshooting evidence. (low confidence) (verified as of 2023-10-09) [source]
Comparisons and alternatives
- MongoDB 6.3 and later supports manual fixed-window bucketing with bucketMaxSpanSeconds and bucketRoundingSeconds instead of granularity. The two values must be equal, between 1 and 31,536,000 seconds inclusive, and granularity must be omitted. bucketMaxSpanSeconds limits the oldest-to-newest time range in a bucket. When a new bucket is opened, bucketRoundingSeconds rounds the first measurement's timestamp down to determine the bucket's minimum time. (high confidence) (verified as of 2026-10-14) [source]
Facts and statements
- MongoDB describes granularity as the expected cadence between measurements. Its presets map to bucketRoundingSeconds and bucketMaxSpanSeconds as follows: seconds = 60 and 3,600; minutes = 3,600 and 86,400; hours = 86,400 and 2,592,000. (high confidence) [source]
- In a September 2024 migration discussion, one user reported that custom 3,600-second bucketing made queries slower and the collection larger than using granularity: hours. This is a workload-specific report, not a general benchmark or a contradiction of the fixed-boundary rules. (low confidence) (verified as of 2024-09-04) [source]
Children
- No children recorded.