# Granularity and custom bucketing parameters > Source-anchored research for Granularity and custom bucketing parameters. Run status: COMPLETED. Parent: [MongoDB Time-Series Query and Index Optimization](https://llms-explorer.com/tree/mongodb-time-series-query-and-index-optimization/) · 5 facets · 13 facts · page: https://llms-explorer.com/tree/granularity-and-custom-bucketing-parameters/ ## How it works - MongoDB maps the presets to maximum bucket spans of 1 hour for seconds, 24 hours for minutes, and 30 days for hours; seconds is the default when no bucketing setting is specified. (high confidence) (verified as of 2026-10-22) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) - MongoDB's time-series query rewrite expands bucket-level time predicates using bucketMaxSpanSeconds so it can find measurements inside matching buckets. By implication, a larger span can broaden candidate bucket ranges and, when timeField is the shard key, can broaden shard targeting and reduce time-filter selectivity; validate the effect with representative query windows. (medium confidence) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/README.md) ## Measurements and reference values - MongoDB's current limitations page caps a bucket at 1,000 measurements or 125KB of data, whichever is lower, and says high-cardinality workloads may have a lower maximum. A bucket can therefore close before reaching its configured time span. (high confidence) (verified as of 2026-10-14) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-limitations.md) ## Problems, failure modes and limitations - Custom bucketing uses bucketMaxSpanSeconds to limit the time range in a bucket and bucketRoundingSeconds to round a new bucket's start down to an interval boundary. Set both parameters to the same positive value, omit granularity, and keep the value within 1–31,536,000 seconds. MongoDB documents these options as available starting in version 6.3. (high confidence) (verified as of 2026-10-20) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) - After collection creation, collMod can increase granularity or the custom bucket parameters, but it cannot decrease the configured time span; changing custom parameters requires both values. Validate the target interval before increasing it because MongoDB does not provide a supported way to return to a narrower span. (high confidence) (verified as of 2026-10-20) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) - The granularity presets describe the expected measurement cadence for a series, and workload guidance says to choose the preset closest to the interval between consecutive measurements. Granularity is not a server-enforced limit on how frequently writes can arrive. (high confidence) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-best-practices/) - The configured span is a maximum, not a promise that a bucket stays open for that full duration. MongoDB caps bucket capacity at 1,000 measurements or 125 KB, whichever is lower, and high-cardinality data can trigger a lower limit to keep the bucket working set within WiredTiger cache. MongoDB's controlled high- and low-ingestion study found size thresholds can dominate bucket rotation at high ingestion, while time span matters more at lower ingestion. (high confidence) (verified as of 2026-10-22) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-limitations.md) - After creation, collMod can increase but not decrease granularity or custom bucket spans. A change affects new buckets and leaves existing buckets unchanged, so the collection cannot be tuned to smaller spans in place. (high confidence) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) ## Comparisons and alternatives - A MongoDB engineering post dated 2026-02-23 reports that size limits, rather than preset time spans, drove bucket rotation in its high-ingestion test across seconds, minutes, and hours settings. The report shows that granularity alone does not predict bucket count for that workload; the post does not specify enough per-device traffic detail to generalize its timing. (medium confidence) (verified as of 2026-02-23) — [source](https://www.mongodb.com/company/blog/technical/a-practical-study-of-mongodb-time-series-bucket-behavior) ## Facts and statements - MongoDB's seconds, minutes, and hours granularity presets map to maximum bucket spans of 1 hour, 24 hours, and 30 days. Choose a preset around the interval between measurements from each data source represented by a metaField. A preset that is too coarse can increase bucket traversal and query time; a preset that is too fine can create multiple buckets per polling interval with only one measurement in each. (high confidence) (verified as of 2026-10-20) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) - For recurring fixed query windows, such as four-hour periods beginning at midnight, MongoDB recommends setting the custom span and rounding interval to that window so buckets do not overlap across periods; its documentation says this can optimize high query volume and inserts. Treat this as workload-specific guidance, not a guaranteed performance gain. (high confidence) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity/) - A MongoDB Community user reported that cache pressure closed many buckets during a workload configured with a one-year bucketMaxSpanSeconds, producing many one-measurement buckets. This is a reported cache-pressure case, not evidence that a one-year span generally creates sparse buckets. (low confidence) (verified as of 2023-10-19) — [source](https://www.mongodb.com/community/forums/t/suboptimal-bucket-creation-in-timeseries-collection-due-to-cache-pressure/249863) - Choose the span against actual write cadence and query ranges. A span that is too coarse can put more time in each bucket, increasing traversal time and slowing queries; a span that is too fine can create multiple buckets per polling interval, sometimes with only one measurement. Benchmark using the workload's real data and query windows. (high confidence) — [source](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-best-practices/)