diff --git a/content/commands/ts.mrange.md b/content/commands/ts.mrange.md index b016ad17a2..400ff9a386 100644 --- a/content/commands/ts.mrange.md +++ b/content/commands/ts.mrange.md @@ -53,50 +53,9 @@ arguments: optional: true token: ALIGN type: integer - - arguments: - - name: avg - token: AVG - type: pure-token - - name: first - token: FIRST - type: pure-token - - name: last - token: LAST - type: pure-token - - name: min - token: MIN - type: pure-token - - name: max - token: MAX - type: pure-token - - name: sum - token: SUM - type: pure-token - - name: range - token: RANGE - type: pure-token - - name: count - token: COUNT - type: pure-token - - name: std.p - token: STD.P - type: pure-token - - name: std.s - token: STD.S - type: pure-token - - name: var.p - token: VAR.P - type: pure-token - - name: var.s - token: VAR.S - type: pure-token - - name: twa - since: 1.8.0 - token: TWA - type: pure-token - name: aggregator + - name: aggregationType token: AGGREGATION - type: oneof + type: string - name: bucketDuration type: integer - name: buckettimestamp @@ -165,15 +124,14 @@ stack_path: docs/data-types/timeseries summary: Query a range across multiple time series by filters in forward direction syntax: "TS.MRANGE fromTimestamp toTimestamp\n [LATEST]\n [FILTER_BY_TS ts...]\n\ \ [FILTER_BY_VALUE min max]\n [WITHLABELS | ]\n [COUNT\ - \ count]\n [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP\ + \ count]\n [[ALIGN align] AGGREGATION aggregators bucketDuration [BUCKETTIMESTAMP\ \ bt] [EMPTY]]\n FILTER filterExpr...\n [GROUPBY label REDUCE reducer]\n" syntax_fmt: "TS.MRANGE fromTimestamp toTimestamp [LATEST] [FILTER_BY_TS\_Timestamp\n\ \ [Timestamp ...]] [FILTER_BY_VALUE min max] [WITHLABELS |\n SELECTED_LABELS label1\ - \ [label1 ...]] [COUNT\_count] [[ALIGN\_value]\n AGGREGATION\_ bucketDuration\n\ - \ [BUCKETTIMESTAMP] [EMPTY]] FILTER\_\ - \ [GROUPBY label REDUCE\n reducer]" + \ [label1 ...]] [COUNT\_count] [[ALIGN\_value]\n AGGREGATION\ aggregators bucketDuration\ + \ [BUCKETTIMESTAMP]\n [EMPTY]] FILTER\_\ + \ [GROUPBY label REDUCE reducer]" title: TS.MRANGE --- {{< note >}} @@ -288,13 +246,13 @@ Values include:
-AGGREGATION aggregator bucketDuration +AGGREGATION aggregators bucketDuration -per time series, aggregates samples into time buckets, where: +for each time series, aggregates samples into time buckets, where: - - `aggregator` takes one of the following aggregation types: + - `aggregators` is one or more comma-separated aggregator from the following table: - | `aggregator` | Description | + | aggregator | Description | | ------------ | --------------------------------------------------------------- | | `avg` | Arithmetic mean of all non-NaN values | | `sum` | Sum of all non-NaN values | @@ -313,6 +271,11 @@ per time series, aggregates samples into time buckets, where: | `twa` | Time-weighted average over the bucket's timeframe (ignores NaN values) (since RedisTimeSeries 1.8) | - `bucketDuration` is duration of each bucket, in milliseconds. + + Note: `aggregators` can either be a single aggregator or multiple aggregators separated by commas as shown below. + No whitespace is allowed between aggregators. + + AGGREGATION min,avg,max Without `ALIGN`, bucket start times are multiples of `bucketDuration`. @@ -338,7 +301,7 @@ controls how bucket timestamps are reported. is a flag, which, when specified, reports aggregations also for empty buckets. -| `aggregator` | Value reported for each empty bucket | +| `aggregators` | 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. | @@ -354,6 +317,7 @@ Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is report splits time series into groups, each group contains time series that share the same value for the provided label name, then aggregates results in each group. When combined with `AGGREGATION` the `GROUPBY`/`REDUCE` is applied post aggregation stage. +`GROUPBY`/`REDUCE` is not permitted when multiple aggregators are specified. - `label` is label name. A group is created for all time series that share the same value for this label. diff --git a/content/commands/ts.mrevrange.md b/content/commands/ts.mrevrange.md index 55f5fca968..e5e434cf1a 100644 --- a/content/commands/ts.mrevrange.md +++ b/content/commands/ts.mrevrange.md @@ -53,50 +53,9 @@ arguments: optional: true token: ALIGN type: integer - - arguments: - - name: avg - token: AVG - type: pure-token - - name: first - token: FIRST - type: pure-token - - name: last - token: LAST - type: pure-token - - name: min - token: MIN - type: pure-token - - name: max - token: MAX - type: pure-token - - name: sum - token: SUM - type: pure-token - - name: range - token: RANGE - type: pure-token - - name: count - token: COUNT - type: pure-token - - name: std.p - token: STD.P - type: pure-token - - name: std.s - token: STD.S - type: pure-token - - name: var.p - token: VAR.P - type: pure-token - - name: var.s - token: VAR.S - type: pure-token - - name: twa - since: 1.8.0 - token: TWA - type: pure-token - name: aggregator + - name: aggregators token: AGGREGATION - type: oneof + type: string - name: bucketDuration type: integer - name: buckettimestamp @@ -165,15 +124,14 @@ stack_path: docs/data-types/timeseries summary: Query a range across multiple time-series by filters in reverse direction syntax: "TS.MREVRANGE fromTimestamp toTimestamp\n [LATEST]\n [FILTER_BY_TS ts...]\n\ \ [FILTER_BY_VALUE min max]\n [WITHLABELS | ]\n [COUNT\ - \ count]\n [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP\ + \ count]\n [[ALIGN align] AGGREGATION aggregators bucketDuration [BUCKETTIMESTAMP\ \ bt] [EMPTY]]\n FILTER filterExpr...\n [GROUPBY label REDUCE reducer]\n" syntax_fmt: "TS.MREVRANGE fromTimestamp toTimestamp [LATEST]\n [FILTER_BY_TS\_Timestamp\ \ [Timestamp ...]] [FILTER_BY_VALUE min max]\n [WITHLABELS | SELECTED_LABELS label1\ - \ [label1 ...]] [COUNT\_count]\n [[ALIGN\_value] AGGREGATION\_\n\ - \ bucketDuration [BUCKETTIMESTAMP] [EMPTY]] FILTER\_ [GROUPBY label REDUCE\n reducer]" + \ [label1 ...]] [COUNT\_count]\n [[ALIGN\_value] AGGREGATION\ aggregators bucketDuration\n\ + \ [BUCKETTIMESTAMP] [EMPTY]] FILTER\_\ + \ [GROUPBY label REDUCE\n reducer]" title: TS.MREVRANGE --- {{< note >}} @@ -288,13 +246,13 @@ Values include:
-AGGREGATION aggregator bucketDuration +AGGREGATION aggregators bucketDuration -per time series, aggregates samples into time buckets, where: +for each time series, aggregates samples into time buckets, where: - - `aggregator` takes one of the following aggregation types: + - `aggregators` is one or more comma-separated aggregator from the following table: - | `aggregator` | Description | + | aggregator | Description | | ------------ | --------------------------------------------------------------- | | `avg` | Arithmetic mean of all non-NaN values | | `sum` | Sum of all non-NaN values | @@ -313,6 +271,11 @@ per time series, aggregates samples into time buckets, where: | `twa` | Time-weighted average over the bucket's timeframe (ignores NaN values) (since RedisTimeSeries 1.8) | - `bucketDuration` is duration of each bucket, in milliseconds. + + Note: `aggregators` can either be a single aggregator or multiple aggregators separated by commas as shown below. + No whitespace is allowed between aggregators. + + AGGREGATION min,avg,max Without `ALIGN`, bucket start times are multiples of `bucketDuration`. @@ -338,7 +301,7 @@ controls how bucket timestamps are reported. is a flag, which, when specified, reports aggregations also for empty buckets. -| `aggregator` | Value reported for each empty bucket | +| `aggregators` | 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. | @@ -354,6 +317,7 @@ Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is report splits time series into groups, each group contains time series that share the same value for the provided label name, then aggregates results in each group. When combined with `AGGREGATION` the `GROUPBY`/`REDUCE` is applied post aggregation stage. +`GROUPBY`/`REDUCE` is not permitted when multiple aggregators are specified. - `label` is label name. A group is created for all time series that share the same value for this label. diff --git a/content/commands/ts.range.md b/content/commands/ts.range.md index 398a9ed1bc..9ac4654e95 100644 --- a/content/commands/ts.range.md +++ b/content/commands/ts.range.md @@ -39,50 +39,9 @@ arguments: optional: true token: ALIGN type: integer - - arguments: - - name: avg - token: AVG - type: pure-token - - name: first - token: FIRST - type: pure-token - - name: last - token: LAST - type: pure-token - - name: min - token: MIN - type: pure-token - - name: max - token: MAX - type: pure-token - - name: sum - token: SUM - type: pure-token - - name: range - token: RANGE - type: pure-token - - name: count - token: COUNT - type: pure-token - - name: std.p - token: STD.P - type: pure-token - - name: std.s - token: STD.S - type: pure-token - - name: var.p - token: VAR.P - type: pure-token - - name: var.s - token: VAR.S - type: pure-token - - name: twa - since: 1.8.0 - token: TWA - type: pure-token - name: aggregator + - name: aggregators token: AGGREGATION - type: oneof + type: string - name: bucketDuration type: integer - name: buckettimestamp @@ -120,12 +79,11 @@ since: 1.0.0 stack_path: docs/data-types/timeseries summary: Query a range in forward direction syntax: "TS.RANGE key fromTimestamp toTimestamp\n [LATEST]\n [FILTER_BY_TS ts...]\n\ - \ [FILTER_BY_VALUE min max]\n [COUNT count] \n [[ALIGN align] AGGREGATION aggregator\ + \ [FILTER_BY_VALUE min max]\n [COUNT count] \n [[ALIGN align] AGGREGATION aggregators\ \ bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]\n" syntax_fmt: "TS.RANGE key fromTimestamp toTimestamp [LATEST]\n [FILTER_BY_TS\_Timestamp\ \ [Timestamp ...]] [FILTER_BY_VALUE min max]\n [COUNT\_count] [[ALIGN\_value] AGGREGATION\_\ - \n bucketDuration [BUCKETTIMESTAMP] [EMPTY]]" + aggregators bucketDuration [BUCKETTIMESTAMP] [EMPTY]]" title: TS.RANGE --- @@ -204,13 +162,13 @@ is a time bucket alignment control for `AGGREGATION`. It controls the time bucke
-AGGREGATION aggregator bucketDuration +AGGREGATION aggregators bucketDuration -aggregates samples into time buckets, where: +for each time series, aggregates samples into time buckets, where: - - `aggregator` takes one of the following aggregation types: + - `aggregators` is one or more comma-separated aggregator from the following table: - | `aggregator` | Description | + | aggregator | Description | | ------------ | --------------------------------------------------------------- | | `avg` | Arithmetic mean of all non-NaN values | | `sum` | Sum of all non-NaN values | @@ -229,6 +187,11 @@ aggregates samples into time buckets, where: | `twa` | Time-weighted average over the bucket's timeframe (ignores NaN values) (since RedisTimeSeries 1.8) | - `bucketDuration` is duration of each bucket, in milliseconds. + + Note: `aggregators` can either be a single aggregator or multiple aggregators separated by commas as shown below. + No whitespace is allowed between aggregators. + + AGGREGATION min,avg,max Without `ALIGN`, bucket start times are multiples of `bucketDuration`. @@ -254,7 +217,7 @@ controls how bucket timestamps are reported. is a flag, which, when specified, reports aggregations also for empty buckets. -| `aggregator` | Value reported for each empty bucket | +| `aggregators` | 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. | @@ -297,12 +260,14 @@ TS.RANGE temp:TLV - + FILTER_BY_VALUE -100 100 2) 40 {{< / highlight >}} -Now, retrieve the average value, while ignoring out-of-range values. +Now, retrieve the minimum, average, and maximum values, while ignoring out-of-range values. {{< highlight bash >}} -TS.RANGE temp:TLV - + FILTER_BY_VALUE -100 100 AGGREGATION avg 1000 +TS.RANGE temp:TLV - + FILTER_BY_VALUE -100 100 AGGREGATION min,avg,max 1000 1) 1) (integer) 1000 - 2) 35 + 2) 30 + 3) 35 + 4) 40 {{< / highlight >}}
diff --git a/content/commands/ts.revrange.md b/content/commands/ts.revrange.md index 450f590d8c..3ebbc76ca7 100644 --- a/content/commands/ts.revrange.md +++ b/content/commands/ts.revrange.md @@ -39,50 +39,9 @@ arguments: optional: true token: ALIGN type: integer - - arguments: - - name: avg - token: AVG - type: pure-token - - name: first - token: FIRST - type: pure-token - - name: last - token: LAST - type: pure-token - - name: min - token: MIN - type: pure-token - - name: max - token: MAX - type: pure-token - - name: sum - token: SUM - type: pure-token - - name: range - token: RANGE - type: pure-token - - name: count - token: COUNT - type: pure-token - - name: std.p - token: STD.P - type: pure-token - - name: std.s - token: STD.S - type: pure-token - - name: var.p - token: VAR.P - type: pure-token - - name: var.s - token: VAR.S - type: pure-token - - name: twa - since: 1.8.0 - token: TWA - type: pure-token - name: aggregator + - name: aggregators token: AGGREGATION - type: oneof + type: string - name: bucketDuration type: integer - name: buckettimestamp @@ -120,12 +79,12 @@ since: 1.4.0 stack_path: docs/data-types/timeseries summary: Query a range in reverse direction syntax: "TS.REVRANGE key fromTimestamp toTimestamp\n [LATEST]\n [FILTER_BY_TS ts...]\n\ - \ [FILTER_BY_VALUE min max]\n [COUNT count]\n [[ALIGN align] AGGREGATION aggregator\ + \ [FILTER_BY_VALUE min max]\n [COUNT count]\n [[ALIGN align] AGGREGATION aggregators\ \ bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]\n" syntax_fmt: "TS.REVRANGE key fromTimestamp toTimestamp [LATEST]\n [FILTER_BY_TS\_\ Timestamp [Timestamp ...]] [FILTER_BY_VALUE min max]\n [COUNT\_count] [[ALIGN\_\ - value] AGGREGATION\_\n bucketDuration [BUCKETTIMESTAMP] [EMPTY]]" + value] AGGREGATION\_aggregators\n bucketDuration [BUCKETTIMESTAMP]\ + \ [EMPTY]]" title: TS.REVRANGE --- @@ -205,12 +164,13 @@ Values include:
-AGGREGATION aggregator bucketDuration -aggregates samples into time buckets, where: +AGGREGATION aggregators bucketDuration - - `aggregator` takes one of the following aggregation types: +for each time series, aggregates samples into time buckets, where: - | `aggregator` | Description | + - `aggregators` is one or more comma-separated aggregator from the following table: + + | aggregator | Description | | ------------ | --------------------------------------------------------------- | | `avg` | Arithmetic mean of all non-NaN values | | `sum` | Sum of all non-NaN values | @@ -229,7 +189,12 @@ aggregates samples into time buckets, where: | `twa` | Time-weighted average over the bucket's timeframe (ignores NaN values) (since RedisTimeSeries 1.8) | - `bucketDuration` is duration of each bucket, in milliseconds. - + + Note: `aggregators` can either be a single aggregator or multiple aggregators separated by commas as shown below. + No whitespace is allowed between aggregators. + + AGGREGATION min,avg,max + Without `ALIGN`, bucket start times are multiples of `bucketDuration`. With `ALIGN align`, bucket start times are multiples of `bucketDuration` with remainder `align % bucketDuration`. @@ -253,7 +218,7 @@ controls how bucket timestamps are reported. [EMPTY] (since RedisTimeSeries 1.8) is a flag, which, when specified, reports aggregations also for empty buckets. -| `aggregator` | Value reported for each empty bucket | +| `aggregators` | 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. | @@ -297,12 +262,14 @@ TS.REVRANGE temp:TLV - + FILTER_BY_VALUE -100 100 2) 30 {{< / highlight >}} -Now, retrieve the average value, while ignoring out-of-range values. +Now, retrieve the minimum, average, and maximum values, while ignoring out-of-range values. {{< highlight bash >}} -TS.REVRANGE temp:TLV - + FILTER_BY_VALUE -100 100 AGGREGATION avg 1000 +TS.REVRANGE temp:TLV - + FILTER_BY_VALUE -100 100 AGGREGATION min,avg,max 1000 1) 1) (integer) 1000 - 2) 35 + 2) 30 + 3) 35 + 4) 40 {{< / highlight >}}
diff --git a/content/develop/data-types/timeseries/_index.md b/content/develop/data-types/timeseries/_index.md index c9117d1af8..2c7eb97146 100644 --- a/content/develop/data-types/timeseries/_index.md +++ b/content/develop/data-types/timeseries/_index.md @@ -383,7 +383,7 @@ bucket by an aggregate value, such as the average or maximum value. For example, if you expect to collect more than one billion data points in a day, you could aggregate the data using buckets of one minute. Since each bucket is represented by a single value, this reduces the dataset size to 1,440 data points (24 hours x 60 minutes = 1,440 minutes). -The range query commands let you specify an aggregation function and bucket size. +The range query commands let you specify one or more aggregation functions and bucket size. The available aggregation functions are: - `avg`: Arithmetic mean of all values @@ -418,6 +418,12 @@ aggregated values with only one value used to calculate the average for the last ``` {{< /clients-example >}} +To use multiple aggregators in a single query, separate the aggregators with comma characters as in the following example. + +```bash +TS.RANGE rg:2 - + AGGREGATION min,avg,max 2 +``` + NaN Handling (Redis 8.6+): Starting from Redis 8.6, all existing aggregation functions ignore NaN values when computing results. For example, if a bucket contains values [1.0, NaN, 3.0], the `avg` aggregator will return 2.0 (average of 1.0 and 3.0), and the `count` aggregator will return 2. Use the new `countNaN` and `countAll` aggregators to count NaN values and total values respectively. ### Bucket alignment diff --git a/static/images/railroad/ts.mrange.svg b/static/images/railroad/ts.mrange.svg index 8e422fa8c2..c4949d5188 100644 --- a/static/images/railroad/ts.mrange.svg +++ b/static/images/railroad/ts.mrange.svg @@ -1,4 +1,4 @@ - + - + TS.MRANGE fromTimestamp toTimestamp @@ -78,64 +78,51 @@ circle { fill: #DC382D !important; stroke: #DC382D !important; } 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,...) - - - - -FILTER - -l=v -l!=v -l= -l!= -l=(v1,v2,...) -l!=(v1,v2,...) - - - - -GROUPBY -label -REDUCE -reducer \ No newline at end of file + +AGGREGATION +aggregators +bucketDuration + + +BUCKETTIMESTAMP + + +EMPTY + + +FILTER + +l=v +l!=v +l= +l!= +l=(v1,v2,...) +l!=(v1,v2,...) + + + + +FILTER + +l=v +l!=v +l= +l!= +l=(v1,v2,...) +l!=(v1,v2,...) + + + + +GROUPBY +label +REDUCE +reducer \ No newline at end of file diff --git a/static/images/railroad/ts.mrevrange.svg b/static/images/railroad/ts.mrevrange.svg index c7aa3437a1..cbc1eae947 100644 --- a/static/images/railroad/ts.mrevrange.svg +++ b/static/images/railroad/ts.mrevrange.svg @@ -1,4 +1,4 @@ - + - + TS.MREVRANGE fromTimestamp toTimestamp - -LATEST + +LATEST @@ -78,64 +78,51 @@ circle { fill: #DC382D !important; stroke: #DC382D !important; } 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,...) - - - - -FILTER - -l=v -l!=v -l= -l!= -l=(v1,v2,...) -l!=(v1,v2,...) - - - - -GROUPBY -label -REDUCE -reducer \ No newline at end of file + +AGGREGATION +aggregators +bucketDuration + + +BUCKETTIMESTAMP + + +EMPTY + + +FILTER + +l=v +l!=v +l= +l!= +l=(v1,v2,...) +l!=(v1,v2,...) + + + + +FILTER + +l=v +l!=v +l= +l!= +l=(v1,v2,...) +l!=(v1,v2,...) + + + + +GROUPBY +label +REDUCE +reducer \ No newline at end of file diff --git a/static/images/railroad/ts.range.svg b/static/images/railroad/ts.range.svg index 295c82a2aa..cfffdcad2e 100644 --- a/static/images/railroad/ts.range.svg +++ b/static/images/railroad/ts.range.svg @@ -1,4 +1,4 @@ - + - + TS.RANGE key fromTimestamp @@ -70,34 +70,21 @@ circle { fill: #DC382D !important; stroke: #DC382D !important; } 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 \ No newline at end of file + +AGGREGATION +aggregators +bucketDuration + + +BUCKETTIMESTAMP + + +EMPTY \ No newline at end of file diff --git a/static/images/railroad/ts.revrange.svg b/static/images/railroad/ts.revrange.svg index 164c7297b9..83769d4403 100644 --- a/static/images/railroad/ts.revrange.svg +++ b/static/images/railroad/ts.revrange.svg @@ -1,4 +1,4 @@ - + - + TS.REVRANGE key fromTimestamp @@ -70,34 +70,29 @@ circle { fill: #DC382D !important; stroke: #DC382D !important; } 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 \ No newline at end of file + +AGGREGATION +aggregators +bucketDuration + + + +BUCKETTIMESTAMP + +- +start ++ +end +~ +mid + + +EMPTY \ No newline at end of file