For a fleet dashboard on Redis time series, how do TS.RANGE with AGGREGATION and TS.MRANGE with FILTER and GROUPBY differ, and what do they reply?
answer
- one key versus a label query
- buckets across time, reducers across series
- bucket first, then reduce
- at least one positive matcher
- raw and rollup can both match
basics
~20 sTS.RANGE reads one key and can bucket it with AGGREGATION, replying with timestamp and value pairs. TS.MRANGE finds series by a label FILTER, replies per series, and GROUPBY with REDUCE combines same-timestamp values across each group.
solid answer
~50 s`TS.RANGE key from to AGGREGATION avg 60000` reads one series, splits time into buckets and replies with timestamp and value pairs, each stamped with the bucket's start. Empty buckets are left out unless you pass `EMPTY`, and comma-separated aggregators return one tuple per bucket. `TS.MRANGE from to FILTER site=berlin` takes no key: it selects series by label and replies per series with key name, labels and samples. The filter needs at least one `l=v` or `l=(v1,v2)` matcher. `GROUPBY site REDUCE max` then merges each group, but `REDUCE` only combines values at the same timestamp, so devices reporting at different milliseconds must be bucketed first with `AGGREGATION`, which runs before the reduce. `GROUPBY` allows only one aggregator. Label raw and rollup series differently, or a filter matches both and `GROUPBY` merges them. In Redis Cluster, `TS.MRANGE` runs across all shards and cannot join a transaction.
code
plaintext · 27 linesTS.CREATE temp:{dev7} LABELS site berlin res raw
OK
TS.CREATE temp:{dev9} LABELS site berlin res raw
OK
TS.MADD temp:{dev7} 1000 21 temp:{dev7} 31000 22 temp:{dev7} 61000 23
1) (integer) 1000
2) (integer) 31000
3) (integer) 61000
TS.MADD temp:{dev9} 5000 19 temp:{dev9} 65000 20
1) (integer) 5000
2) (integer) 65000
TS.RANGE temp:{dev7} 0 120000 AGGREGATION min,avg,max 60000
1) 1) (integer) 0
2) 21
3) 21.5
4) 22
2) 1) (integer) 60000
2) 23
3) 23
4) 23
TS.MRANGE 0 120000 AGGREGATION avg 60000 FILTER site=berlin res=raw GROUPBY site REDUCE max
1) 1) "site=berlin"
2) (empty array)
3) 1) 1) (integer) 0
2) 21.5
2) 1) (integer) 60000
2) 23go deeper
Know that TS.RANGE reads one key between two timestamps, that AGGREGATION adds buckets in milliseconds, and that TS.MRANGE selects series by label through FILTER instead of by key.
Predict the replies: pairs or tuples per bucket from TS.RANGE, one element per series from TS.MRANGE, and a label=value series from GROUPBY. Explain that AGGREGATION runs before REDUCE.
Catch the failure modes: reducers combining only identical timestamps, a filter matching raw and rollup together, and a single unreadable key failing the entire TS.MRANGE under ACLs.
Treat the label schema as an interface every dashboard depends on, deciding which labels exist and how resolutions are marked, since TS.ALTER must then rewrite them key by key.
## Two commands, two axes A dashboard over a fleet of temperature sensors asks two kinds of question. "What did device 7 do this hour?" reads one series. "What was the hottest reading at each site this hour?" reads many. `TS.RANGE` serves the first and `TS.MRANGE` the second. ## TS.RANGE: one key, buckets over time `TS.RANGE key fromTimestamp toTimestamp` returns samples in ascending time order, and `TS.REVRANGE` does the same in descending order. Both bounds are inclusive, and `-` and `+` mean the earliest and latest samples. A missing key is an error rather than an empty reply. Adding `AGGREGATION aggregator bucketDuration` turns raw samples into buckets: - **Aggregators** include `avg`, `sum`, `min`, `max`, `range`, `count`, `first`, `last`, `std.p`, `std.s`, `var.p`, `var.s` and `twa`. Comma-separated lists such as `min,avg,max` return one tuple per bucket. - **Bucket timestamps** report the bucket's start unless `BUCKETTIMESTAMP` says otherwise. - **Alignment** defaults to 0, so bucket starts are multiples of the duration. `ALIGN` moves the grid. - **Empty buckets** are not reported unless you pass `EMPTY`, which gives 0 for `sum` and `count`, the previous value for `last`, and `NaN` for most others. - **Filters** such as `FILTER_BY_VALUE` run before aggregation, which is how you exclude a sentinel value from an average. - **`COUNT`** caps the samples returned or, with `AGGREGATION`, the buckets. The aggregation runs at read time over the samples in the range. Over a day of raw one-second samples, that means reading tens of thousands of points for each chart, which is why long windows should read a compaction series instead. On such a series, add `LATEST` so the chart's line reaches the open bucket. ## TS.MRANGE: many keys, chosen by label `TS.MRANGE` drops the key argument and requires `FILTER`. The expressions work on labels: | Expression | Meaning | |---|---| | `l=v` | Label equals the value | | `l=(v1,v2)` | Label equals one of the values | | `l!=v` | Label differs from the value | | `l!=(v1,v2)` | Label is none of the values | | `l=` | Series has no such label | | `l!=` | Series has that label | The source insists on at least one positive matcher, `l=v` or `l=(v1,v2)`. `FILTER site!=berlin` on its own fails with `TSDB: please provide at least one matcher`. The reply holds one element per matching series: key name, labels, samples. Labels are an empty array unless you pass `WITHLABELS` or `SELECTED_LABELS`. Series with no samples in the range are still reported with an empty sample list, and Redis 8.10 added `EXCLUDEEMPTY` to leave them out, though it cannot be combined with `GROUPBY`. `AGGREGATION` here applies per series, so each device is bucketed separately before any grouping. ## GROUPBY and REDUCE: across series `GROUPBY label REDUCE reducer` merges series sharing a label value into one result, named `label=value`, such as `site=berlin`. Order matters: 1. `FILTER` picks the series. 2. `AGGREGATION`, if present, buckets each series. 3. `REDUCE` combines values that have the **same timestamp** in each group. Step 3 is the trap. `REDUCE` does not snap nearby readings together. If device 7 reports at 1000 ms and device 9 at 1001 ms, a raw `REDUCE max` reports both timestamps, each computed from one device. Adding `AGGREGATION avg 60000` puts them on a shared grid, and then the reduction means what the chart title says. Two limits follow. `GROUPBY` with several aggregators is not permitted. And `first`, `last` and `twa` are aggregators but not reducers; the source rejects them after `REDUCE`. With `WITHLABELS`, a grouped result carries `__reducer__` and `__source__`, the second listing the contributing keys, which is handy for debugging. ## Label design and permissions Label series so a filter cannot catch two resolutions. If raw and one-minute series both carry `site=berlin`, then `FILTER site=berlin` returns both, and a `GROUPBY` merges them. Adding a label such as `res=raw` or `res=1m` and filtering on it prevents that. `TS.MRANGE` replies only if the current ACL user can read every key matching the filter; otherwise the whole command fails. ## In Redis Cluster `TS.MRANGE` is a cross-slot command that runs on all shards, and it cannot be part of a transaction. `ts-num-threads`, default 3, caps per-shard threads for such queries, while the 8.10 `TS.NRANGE` takes an explicit key list in one hash slot instead.
- Why does a Redis TS.MRANGE with GROUPBY return many sparse timestamps instead of one line per minute?`REDUCE` combines only values at identical timestamps. Without `AGGREGATION`, each device's reporting milliseconds stay distinct, so most timestamps carry just one device's value and the reducer does nothing useful. Add `AGGREGATION avg 60000` before `FILTER`. Each series is then bucketed onto a shared grid, and the reducer combines the buckets.
- What does a Redis TS.RANGE with AGGREGATION cost compared with reading a compaction series?Query-time aggregation walks every raw sample in the range, so its cost grows with the window. A compaction series already holds one sample per bucket, so the same chart reads far fewer points, at the price of extra write work and a fixed choice of aggregator and bucket. Short windows and ad-hoc buckets suit raw; long fixed charts suit rollups.
- TS.MRANGE takes a list of key names, just as TS.RANGE takes one.
- REDUCE lines up readings that are merely close together in time.
- Buckets with no samples come back as zeros unless you say otherwise.
- A negative label filter such as site!=berlin works on its own.
- GROUPBY can be combined with several comma-separated aggregators.
- A filter on a shared label automatically skips compaction series.
Assumes Redis 8.10, which added EXCLUDEEMPTY on TS.MRANGE; NaN handling in aggregators dates from 8.6.