TS.MRANGE fromTimestamp toTimestamp [FILTER_BY_TS Timestamp [Timestamp ...]] [ FILTER_BY_VALUE min max] [ WITHLABELS | SELECTED_LABELS label1 [label1 ...]] [COUNT count] [ [ALIGN value] AGGREGATION AVG | FIRST | LAST | MIN | MAX | SUM | RANGE | COUNT | STD.P | STD.S | VAR.P | VAR.S | TWA bucketDuration [BUCKETTIMESTAMP] [EMPTY]] FILTER l=v | l!=v | l= | l!= | l=(v1,v2,...) | l!=(v1,v2,...) [ l=v | l!=v | l= | l!= | l=(v1,v2,...) | l!=(v1,v2,...) ...] [ GROUPBY label REDUCE reducer]

Available in: Redis Stack

Time complexity: O(n/m+k) where n = Number of data points, m = Chunk size (data points per chunk), k = Number of data points that are in the requested ranges

TS.MRANGE

Query a range across multiple time series by filters in forward direction.

TS.MRANGE fromTimestamp toTimestamp
          [FILTER_BY_TS TS...]
          [FILTER_BY_VALUE min max]
          [WITHLABELS | SELECTED_LABELS label...]
          [COUNT count]
          [[ALIGN value] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]
          FILTER filter..
          [GROUPBY label REDUCE reducer]

  • fromTimestamp - Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).

  • toTimestamp - End timestamp for range query, + can be used to express the maximum possible timestamp.

  • FILTER filter...

    This is the list of possible filters:

    • label=value - label equals value
    • label!=value - label doesn't equal value
    • label= - key does not have the label label
    • label!= - key has label label
    • label=(value1,value2,...) - key with label label that equals one of the values in the list
    • lable!=(value1,value2,...) - key with label label that doesn't equal any of the values in the list

    Note: Whenever filters need to be provided, a minimum of one label=value filter must be applied.

Optional parameters:

  • FILTER_BY_TS ts... - Followed by a list of timestamps to filter the result by specific timestamps

  • FILTER_BY_VALUE min max - Filter result by value using minimum and maximum.

  • WITHLABELS - Include in the reply all label-value pairs representing metadata labels of the time series.

    If WITHLABELS or SELECTED_LABELS are not specified, by default, an empty list is reported as the label-value pairs.

  • SELECTED_LABELS label... - Include in the reply a subset of the label-value pairs that represent metadata labels of the time series. This is usefull when there is a large number of labels per series, but only the values of some of the labels are required.

    If WITHLABELS or SELECTED_LABELS are not specified, by default, an empty list is reported as the label-value pairs.

  • COUNT count - Maximum number of returned samples per time series.

  • ALIGN value - Time bucket alignment control for AGGREGATION. This will control the time bucket timestamps by changing the reference timestamp on which a bucket is defined. Possible values:

    • start or -: The reference timestamp will be the query start interval time (fromTimestamp) which can't be -
    • end or +: The reference timestamp will be the query end interval time (toTimestamp) which can't be +
    • A specific timestamp: align the reference timestamp to a specific time
    • Note: when not provided, alignment is set to 0

  • AGGREGATION aggregator bucketDuration

    Aggregate results into time buckets.

    • aggregator - Aggregation type: One of the following:
      aggregatordescription
      avgarithmetic mean of all values
      sumsum of all values
      minminimum value
      maxmaximum value
      rangedifference between the highest and the lowest value
      countnumber of values
      firstthe value with the lowest timestamp in the bucket
      lastthe value with the highest timestamp in the bucket
      std.ppopulation standard deviation of the values
      std.ssample standard deviation of the values
      var.ppopulation variance of the values
      var.ssample variance of the values
      twatime-weighted average of all values
    • bucketDuration - duration of each bucket, in milliseconds

    The alignment of time buckets is 0.

  • GROUPBY label REDUCE reducer

    Aggregate results across different time series, grouped by the provided label name.

    When combined with AGGREGATION the groupby/reduce is applied post aggregation stage.

    • label - label name to group series by. A new series for each value will be produced.
    • reducer - Reducer type used to aggregate series that share the same label value. One of the following:
      reducerdescription
      avgper label value: arithmetic mean of all values
      sumper label value: sum of all values
      minper label value: minimum value
      maxper label value: maximum value
      rangeper label value: difference between the highest and the lowest value
      countper label value: number of values
      std.pper label value: population standard deviation of the values
      std.sper label value: sample standard deviation of the values
      var.pper label value: population variance of the values
      var.sper label value: sample variance of the values
    • Note: The produced time series will be named <label>=<groupbyvalue>
    • Note: The produced time series will contain 2 labels with the following label array structure:
      • __reducer__ : the reducer used
      • __source__ : the time series keys used to compute the grouped series ("key1,key2,key3,...")

Return Value

For each time series matching the specified filters, the following is reported:

  • The key name
  • A list of label-value pairs
    • By default, an empty list is reported
    • If WITHLABELS is specified, all labels associated with this time series are reported
    • If SELECTED_LABELS label... is specified, the selected labels are reported
  • timestamp-value pairs for all samples/aggregations matching the range

Note: MRANGE command can't be part of transaction when running on Redis cluster.

Examples

Query by Filters Example
127.0.0.1:6379> TS.MRANGE 1548149180000 1548149210000 AGGREGATION avg 5000 FILTER area_id=32 sensor_id!=1
1) 1) "temperature:2:32"
   2) (empty list or set)
   3) 1) 1) (integer) 1548149180000
         2) "27.600000000000001"
      2) 1) (integer) 1548149185000
         2) "23.800000000000001"
      3) 1) (integer) 1548149190000
         2) "24.399999999999999"
      4) 1) (integer) 1548149195000
         2) "24"
      5) 1) (integer) 1548149200000
         2) "25.600000000000001"
      6) 1) (integer) 1548149205000
         2) "25.800000000000001"
      7) 1) (integer) 1548149210000
         2) "21"
2) 1) "temperature:3:32"
   2) (empty list or set)
   3) 1) 1) (integer) 1548149180000
         2) "26.199999999999999"
      2) 1) (integer) 1548149185000
         2) "27.399999999999999"
      3) 1) (integer) 1548149190000
         2) "24.800000000000001"
      4) 1) (integer) 1548149195000
         2) "23.199999999999999"
      5) 1) (integer) 1548149200000
         2) "25.199999999999999"
      6) 1) (integer) 1548149205000
         2) "28"
      7) 1) (integer) 1548149210000
         2) "20"
Query by Filters Example with WITHLABELS option
127.0.0.1:6379> TS.MRANGE 1548149180000 1548149210000 AGGREGATION avg 5000 WITHLABELS FILTER area_id=32 sensor_id!=1
1) 1) "temperature:2:32"
   2) 1) 1) "sensor_id"
         2) "2"
      2) 1) "area_id"
         2) "32"
   3) 1) 1) (integer) 1548149180000
         2) "27.600000000000001"
      2) 1) (integer) 1548149185000
         2) "23.800000000000001"
      3) 1) (integer) 1548149190000
         2) "24.399999999999999"
      4) 1) (integer) 1548149195000
         2) "24"
      5) 1) (integer) 1548149200000
         2) "25.600000000000001"
      6) 1) (integer) 1548149205000
         2) "25.800000000000001"
      7) 1) (integer) 1548149210000
         2) "21"
2) 1) "temperature:3:32"
   2) 1) 1) "sensor_id"
         2) "3"
      2) 1) "area_id"
         2) "32"
   3) 1) 1) (integer) 1548149180000
         2) "26.199999999999999"
      2) 1) (integer) 1548149185000
         2) "27.399999999999999"
      3) 1) (integer) 1548149190000
         2) "24.800000000000001"
      4) 1) (integer) 1548149195000
         2) "23.199999999999999"
      5) 1) (integer) 1548149200000
         2) "25.199999999999999"
      6) 1) (integer) 1548149205000
         2) "28"
      7) 1) (integer) 1548149210000
         2) "20"
Query time series with metric=cpu, group them by metric_name reduce max
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric_name system
(integer) 1
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 2
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric_name user
(integer) 2
127.0.0.1:6379> TS.MRANGE - + WITHLABELS FILTER metric=cpu GROUPBY metric_name REDUCE max
1) 1) "metric_name=system"
   2) 1) 1) "metric_name"
         2) "system"
      2) 1) "__reducer__"
         2) "max"
      3) 1) "__source__"
         2) "ts1"
   3) 1) 1) (integer) 1548149180000
         2) 90
      2) 1) (integer) 1548149185000
         2) 45
2) 1) "metric_name=user"
   2) 1) 1) "metric_name"
         2) "user"
      2) 1) "__reducer__"
         2) "max"
      3) 1) "__source__"
         2) "ts2"
   3) 1) 1) (integer) 1548149180000
         2) 99
Query time series with metric=cpu, filter values larger or equal to 90.0 and smaller or equal to 100.0
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric_name system
(integer) 1
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 2
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric_name user
(integer) 2
127.0.0.1:6379> TS.MRANGE - + FILTER_BY_VALUE 90 100 WITHLABELS FILTER metric=cpu
1) 1) "ts1"
   2) 1) 1) "metric"
         2) "cpu"
      2) 1) "metric_name"
         2) "system"
   3) 1) 1) (integer) 1548149180000
         2) 90
2) 1) "ts2"
   2) 1) 1) "metric"
         2) "cpu"
      2) 1) "metric_name"
         2) "user"
   3) 1) 1) (integer) 1548149180000
         2) 99
Query time series with metric=cpu, but only reply the team label
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric_name system team NY
(integer) 1
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 2
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric_name user team SF
(integer) 2
127.0.0.1:6379> TS.MRANGE - + SELECTED_LABELS team FILTER metric=cpu
1) 1) "ts1"
   2) 1) 1) "team"
         2) "NY"
   3) 1) 1) (integer) 1548149180000
         2) 90
      2) 1) (integer) 1548149185000
         2) 45
2) 1) "ts2"
   2) 1) 1) "team"
         2) "SF"
   3) 1) 1) (integer) 1548149180000
         2) 99
Edit this page Create documentation issue