content/commands/ts.revrange.md
Query a range in reverse direction. Starting from Redis 8.6, NaN values are included in raw measurement reports (queries without aggregation).
is the key name for the time series.
</details> <details open> <summary><code>fromTimestamp</code></summary>is start timestamp for the range query (integer Unix timestamp in milliseconds) or - to denote the timestamp of the earliest sample in the time series.
is end timestamp for the range query (integer Unix timestamp in milliseconds) or + to denote the timestamp of the latest sample in the time series.
<note><b>Note:</b> When the time series is a compaction, the last compacted value may aggregate raw values with timestamp beyond toTimestamp. That is because toTimestamp limits only the timestamp of the compacted value, which is the start time of the raw bucket that was compacted.</note>
is used when a time series is a compaction. With LATEST, TS.REVRANGE also reports the compacted value of the latest, possibly partial, bucket, given that this bucket's start time falls within [fromTimestamp, toTimestamp]. Without LATEST, TS.REVRANGE does not report the latest, possibly partial, bucket. When a time series is not a compaction, LATEST is ignored.
The data in the latest bucket of a compaction is possibly partial. A bucket is closed and compacted only upon arrival of a new sample that opens a new latest bucket. There are cases, however, when the compacted value of the latest, possibly partial, bucket is also required. In such a case, use LATEST.
filters samples by a list of specific timestamps. A sample passes the filter if its exact timestamp is specified and falls within [fromTimestamp, toTimestamp].
When used together with AGGREGATION: samples are filtered before being aggregated.
filters samples by minimum and maximum values. min and max cannot be NaN values.
When used together with AGGREGATION: samples are filtered before being aggregated.
When used without AGGREGATION: limits the number of reported samples.
When used together with AGGREGATION: limits the number of reported buckets.
is a time bucket alignment control for AGGREGATION. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined.
Values include:
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 +<note><b>NOTE:</b> When not provided, alignment is set to 0.</note>
aggregator takes one of the following aggregation types:
aggregator | Description |
|---|---|
avg | Arithmetic mean of all non-NaN values |
sum | Sum of all non-NaN values |
min | Minimum non-NaN value |
max | Maximum non-NaN value |
range | Difference between the maximum and the minimum non-NaN values |
count | Number of non-NaN values |
countNaN | Number of NaN values (since Redis 8.6) |
countAll | Number of values, including NaN and non-NaN (since Redis 8.6) |
first | The non-NaN value with the lowest timestamp in the bucket |
last | The non-NaN value with the highest timestamp in the bucket |
std.p | Population standard deviation of the non-NaN values |
std.s | Sample standard deviation of the non-NaN values |
var.p | Population variance of the non-NaN values |
var.s | Sample variance of the non-NaN values |
twa | Time-weighted average over the bucket's timeframe (ignores NaN values) (since RedisTimeSeries 1.8) |
bucketDuration is duration of each bucket, in milliseconds.
Without ALIGN, bucket start times are multiples of bucketDuration.
With ALIGN align, bucket start times are multiples of bucketDuration with remainder align % bucketDuration.
The first bucket start time is less than or equal to fromTimestamp.
controls how bucket timestamps are reported.
bt | Timestamp reported for each bucket |
|---|---|
- or start | the bucket's start time (default) |
+ or end | the bucket's end time |
~ or mid | the bucket's mid time (rounded down if not an integer) |
aggregator | Value reported for each empty bucket |
|---|---|
sum, count | 0 |
last | The value of the last sample before the bucket's start. NaN when no such sample. |
twa | Average value over the bucket's timeframe based on linear interpolation of the last sample before the bucket's start and the first sample after the bucket's end. NaN when no such samples. |
min, max, range, avg, first, std.p, std.s | NaN |
Regardless of the values of fromTimestamp and toTimestamp, no data is reported for buckets that end before the earliest sample or begin after the latest sample in the time series.
TS.REVRANGE complexity can be improved in the future by using binary search to find the start of the range, which makes this O(Log(n/m)+k*m).
But, because m is small, you can disregard it and look at the operation as O(Log(n)+k).
Consider a metric where acceptable values are between -100 and 100, and the value 9999 is used as an indication of bad measurement.
{{< highlight bash >}} 127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV OK 127.0.0.1:6379> TS.MADD temp:TLV 1000 30 temp:TLV 1010 35 temp:TLV 1020 9999 temp:TLV 1030 40
Now, retrieve all values except out-of-range values.
{{< highlight bash >}} TS.REVRANGE temp:TLV - + FILTER_BY_VALUE -100 100
Now, retrieve the average value, while ignoring out-of-range values.
{{< highlight bash >}} TS.REVRANGE temp:TLV - + FILTER_BY_VALUE -100 100 AGGREGATION avg 1000
To demonstrate alignment, let’s create a stock and add prices at three different timestamps.
{{< highlight bash >}} 127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A OK 127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
Next, aggregate without using ALIGN, defaulting to alignment 0.
{{< highlight bash >}} 127.0.0.1:6379> TS.REVRANGE stock:A - + AGGREGATION min 20
And now set ALIGN to 10 to have a bucket start at time 10, and align all the buckets with a 20 milliseconds duration.
{{< highlight bash >}} 127.0.0.1:6379> TS.REVRANGE stock:A - + ALIGN 10 AGGREGATION min 20
When the start timestamp for the range query is explicitly stated (not -), you can set ALIGN to that time by setting align to - or to start.
{{< highlight bash >}} 127.0.0.1:6379> TS.REVRANGE stock:A 5 + ALIGN - AGGREGATION min 20
Similarly, when the end timestamp for the range query is explicitly stated, you can set ALIGN to that time by setting align to + or to end.
| Redis Software | Redis Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> | |:----------------------|:-----------------|:------| | <span title="Supported">✅ Supported</span> | <span title="Supported">✅ Flexible & Annual</span> <span title="Supported">✅ Free & Fixed</nobr></span> | |
{{< multitabs id="ts-revrange-return-info" tab1="RESP2" tab2="RESP3" >}}
One of the following:
-tab-sep-
One of the following:
{{< /multitabs >}}
[TS.RANGE]({{< relref "commands/ts.range/" >}}) | [TS.MRANGE]({{< relref "commands/ts.mrange/" >}}) | [TS.MREVRANGE]({{< relref "commands/ts.mrevrange/" >}})
[RedisTimeSeries]({{< relref "/develop/data-types/timeseries/" >}})