<!-- llms-explorer concept facts · https://llms-explorer.com/tree/time-field-bucket-predicates/ · pack 2026-10-31 · ~2054 tokens -->

# Time-field bucket predicates

> Source-anchored research for Time-field bucket predicates. Run status: COMPLETED.

Parent: [Bucket-level predicate rewriting for measurement operators](https://llms-explorer.com/tree/bucket-level-predicate-rewriting-for-measurement-operators/) · 4 facets · 18 facts · page: https://llms-explorer.com/tree/time-field-bucket-predicates/

## How it works

- The _id timestamp shortcut needs extended-range date handling. SERVER-94207 reproduces a pre-1970 equality query yielding an incorrect EOF plan and identifies conflicting generated bucket predicates as the suspected mechanism. (medium confidence) — [source](https://jira.mongodb.org/browse/SERVER-94207)

## Problems, failure modes and limitations

- SERVER-99527 documents a historical correctness failure: a non-metaField delete can advance control.min while leaving the bucket _id timestamp unchanged; later indexed reopening can admit measurements outside the _id-derived span and time filters can omit results. Its August 7, 2025 advisory identifies affected 7.0.0–7.0.15 and 8.0.0–8.0.3 releases; both related tickets list fixes including 7.0.16 and 8.0.4. (medium confidence) (verified as of 2025-08-07) — [source](https://jira.mongodb.org/browse/SERVER-99527)
- Bucket _id comparisons are an additional rewrite that can enable bounded clustered scans. They require knowledge that the shard has no extended-range time values; BucketSpec warns that mongos cannot assume another shard has the same extended-range state. (medium confidence) (verified as of 2026-10-30) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_spec.h)
- Increasing granularity changes the span used for future time-predicate expansion but does not rewrite existing buckets. A validation check that rounds an old bucket using the new granularity can falsely report a min/max violation; SERVER-95480 documents this case. A validation warning alone does not establish that a time query lost data. (medium confidence) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/README.md)

## Comparisons and alternatives

- control.min for the time field is rounded down when the bucket opens. It need not equal the earliest stored measurement timestamp. The bucket ObjectId time differs from a measurement ObjectId time, which typically reflects insertion. (low confidence) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/timeseries/README.md)

## Facts and statements

- MongoDB rewrites timeField comparisons into bucket control.min/control.max predicates before unpacking; eligible time predicates also generate bucket _id bounds that can enable bounded clustered scans. (medium confidence) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/README.md)
- For a BSON Date equality t = T, the default generator requires min <= T and max >= T, and adds min >= T - S and max <= T + S, where S is bucketMaxSpanSeconds. (low confidence) (verified as of 2026-10-30) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- For default time buckets, t > T or t >= T compares control.max to T and control.min to T - S, preserving strictness. Conversely, t < T or t <= T compares control.min to T and control.max to T + S. (low confidence) (verified as of 2026-10-30) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- Fixed-bucket time rewriting rounds the lower bound to the bucket boundary. Boundary-aligned $gte and $lt predicates can remove the event filter; $gt, $lte and equality still require measurement filtering. (medium confidence) (verified as of 2026-10-30) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/README.md)
- Custom bucketing alone does not establish fixed-bucket optimization eligibility: the query README requires that bucketMaxSpanSeconds and bucketRoundingSeconds have not changed since creation. (low confidence) (verified as of 2026-10-30) — [source](https://github.com/mongodb/mongo/blob/master/src/mongo/db/query/timeseries/README.md)
- An explain COLLSCAN does not imply a scan of individual measurements: Percona demonstrated time equality rewritten into _id and control timestamp bounds on backing buckets in MongoDB 5.0. (medium confidence) — [source](https://www.percona.com/blog/mongodb-5-0-time-series-collections/)
- A Stack Overflow user independently reported documents available by measurement _id but missing from timestamp ranges, alongside bucket _id/control.min mismatch warnings. The later answer relays MongoDB support; that diagnosis is vendor-origin evidence, not independent corroboration. (low confidence) (verified as of 2024-12-11) — [source](https://stackoverflow.com/questions/79141281/mongodb-time-series-collection-fails-to-retrieve-data-when-queried-by-timestamp)
- Time-field comparisons can become bucket filters on control.min.<timeField> and control.max.<timeField> before unpacking. Percona independently shows these control comparisons, plus bucket _id bounds, in explain output for timestamp equality and range queries in MongoDB 5.0. Bucket candidates can still require filtering individual measurements. (medium confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_spec.h)
- In the inspected default generator, let t be the Date operand, S=bucketMaxSpanSeconds in duration units, m=control.min.<timeField>, and M=control.max.<timeField>. Equality generates m<=t AND m>=t-S AND M>=t AND M<=t+S. Greater-than generates M>t AND m>t-S; greater-than-or-equal uses >= on both. Less-than generates m<t AND M<t+S; less-than-or-equal uses <= on both. These are bucket candidate tests, not proof that each measurement matches. (low confidence) (verified as of 2026-10-30) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- The extra time-span-adjusted comparison is deliberate: for time<t, BucketSpec documents both control.min.time<t and control.max.time<t+bucketMaxSpanSeconds. The implementation explains that span bounds help narrow time-index scans and mongos routing. (medium confidence) (verified as of 2026-10-30) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- The inspected comparison generator requires a Date operand for the actual timeField and declines comparisons against non-Date values. It also rejects mapping fields computed by an earlier $addFields/computed projection or removed by projection. Treat a displayed time-like field as eligible only after checking its actual bucket specification and pipeline provenance. (low confidence) (verified as of 2026-10-30) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- With unchanged fixed bucketing, the generator can replace the default t-S lower bound on control.min.time with t rounded down to the fixed interval. Boundary-aligned $gte and $lt predicates can provide an exact bucket selection and permit removal of event filtering; $gt, $lte, and equality retain event filtering. The inspected builder disables fixed-bucket specialization for extended-range data. (medium confidence) (verified as of 2026-10-30) — [source](https://raw.githubusercontent.com/mongodb/mongo/master/src/mongo/db/query/timeseries/bucket_level_comparison_predicate_generator.cpp)
- A Stack Overflow user independently reports that a time-range query omitted documents retrievable by measurement _id, and that export/reimport restored results. This is a firsthand symptom report, not independent proof of the optimizer formulas; the same page later quotes MongoDB support for its deletion-related diagnosis. (low confidence) — [source](https://stackoverflow.com/questions/79141281/mongodb-time-series-collection-fails-to-retrieve-data-when-queried-by-timestamp)