Windowed Aggregations on Time Series

A window function computes a value for each document in a result set by looking at a surrounding range (the 'window') of documents — without collapsing them into a group the way $group does. Each input document produces exactly one output document, but the computed value reflects aggregation across the window. MongoDB added window functions via the $setWindowFields stage in version 5.0.

$setWindowFields is the aggregation stage that enables window functions in MongoDB. It accepts a partitionBy expression (similar to SQL's PARTITION BY), an output object defining new fields and their window operators, and a sortBy document that establishes the ordering within each partition. This combination makes it ideal for time series: partition by sensor, sort by timestamp, compute running totals or moving averages.

Window boundaries can be specified in terms of document positions relative to the current document. The special keywords 'unbounded' (from the first document in the partition) and 'current' (the current document) define common boundaries. You can also use integers: [-3, 0] means the 3 preceding documents and the current one — perfect for a rolling 4-point moving average.

For time series data, range-based windows are more natural than document-based ones because data may not arrive at uniform intervals. Range windows use a unit (milliseconds by default) and an amount relative to the current document's sort value. For example, a 1-hour trailing window would be { range: [-3600000, 0], unit: 'millisecond' }. Dedicated time units like 'hour', 'minute', and 'second' are supported too.

A running total (or cumulative sum) is computed by setting the window from 'unbounded' to 'current'. Each document's output field reflects the sum of all values from the first document in the partition up to and including the current one. This is useful for computing cumulative energy consumption, total transactions, or bytes transferred over time.

$rank and $denseRank are window operators that assign position numbers to documents within their partition, ordered by the sortBy expression. $rank leaves gaps in numbering for ties (1, 2, 2, 4…) while $denseRank does not (1, 2, 2, 3…). These are useful for ranking sensors by their latest reading or identifying top-N performing devices.

$documentNumber assigns a sequential integer starting at 1 to each document within its partition, ordered by sortBy. Unlike $rank, it never produces ties — every document gets a unique number. This is handy for pagination, batch numbering of exports, or labelling sequential events in a sensor stream.

The $shift operator accesses the value of a field from a document at a relative position. { $shift: { output: '$temperature', by: -1 } } returns the temperature from the previous document in the partition. This is perfect for computing deltas — the difference between the current reading and the one before it — which reveals rate-of-change in sensor data.

Always place a $match stage before $setWindowFields to reduce the working set. Window computations happen in memory, so feeding fewer documents into the stage significantly reduces RAM usage. After the window stage, you can add another $match to filter the enriched output — for example, keeping only documents where the rolling average exceeds a threshold.

$setWindowFields must hold each partition in memory to compute window values. For time series data, this means one sensor's data for the requested time range. If your partitions are extremely large (millions of measurements), consider pre-filtering with $match or using allowDiskUse: true on the aggregation to spill partitions to disk. Alternatively, pre-aggregate into per-hour summaries before applying window functions.

A complete anomaly detection pipeline combines $match for range filtering, $setWindowFields with a trailing window to compute the rolling average and standard deviation, and a final $match with $expr to surface readings that deviate more than 2 standard deviations from the local mean. This pattern forms the backbone of real-time IoT monitoring systems.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: $setWindowFields enriches each document with values computed over a surrounding window without collapsing the result, document and range boundaries give you fine-grained control over trailing, leading, or time-span windows, and operators like $avg, $sum, $shift, and $rank cover moving averages, running totals, delta computation, and ranking. Next up we explore automatic data expiration using expireAfterSeconds.