skip to content

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?

level: middleimportance: should knowfreq 24%

answer

  1. one key versus a label query
  2. buckets across time, reducers across series
  3. bucket first, then reduce
  4. at least one positive matcher
  5. raw and rollup can both match

basics

~20 s

TS.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 lines
plaintext
TS.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) 23

go deeper

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.