Skip to content

DOC-5424 enabled TCEs in time series page #1856

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 21, 2025
Merged

DOC-5424 enabled TCEs in time series page #1856

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 31 additions & 36 deletions content/develop/data-types/timeseries/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,7 @@ command, specifying a key name. Alternatively, if you use [`TS.ADD`]({{< relref
to add data to a time series key that does not exist, it is automatically created (see
[Adding data points](#adding-data-points) below for more information about `TS.ADD`).

<!--< clients-example time_series_tutorial create >}}-->
```bash
{{< clients-example time_series_tutorial create >}}
> TS.CREATE thermometer:1
OK
> TYPE thermometer:1
Expand All @@ -68,8 +67,7 @@ TSDB-TYPE
2) (integer) 0
.
.
```
<!--< /clients-example >}}-->
{{< /clients-example >}}

The timestamp for each data point is a 64-bit integer value. The value
represents a Unix timestamp, measured in milliseconds since the
Expand All @@ -78,10 +76,8 @@ When you create a time series, you can specify a maximum retention period for th
data, relative to the last reported timestamp. A retention period of zero means
the data does not expire.

<!--< clients-example time_series_tutorial create_retention >}} -->
```bash
# Create a new time series with a first value of 10.8 (Celsius),
# recorded at time 1, with a retention period of 100ms.
{{< clients-example time_series_tutorial create_retention >}}
# Create a new time series with a first value of 10.8 (Celsius), recorded at time 1, with a retention period of 100ms.
> TS.ADD thermometer:2 1 10.8 RETENTION 100
(integer) 1
> TS.INFO thermometer:2
Expand All @@ -91,15 +87,14 @@ the data does not expire.
10) (integer) 100
.
.
```
<!--< /clients-example >}}-->
{{< /clients-example >}}

You can also add one or more *labels* to a time series when you create it. Labels
are name-value pairs where both the name and value are strings. You can use
the names and values to select subsets of all the available time series
for queries and aggregations.

<!--< clients-example time_series_tutorial create_labels >}} -->
{{< clients-example time_series_tutorial create_labels >}}
```bash
> TS.ADD thermometer:3 1 10.4 LABELS location UK type Mercury
(integer) 1
Expand All @@ -118,7 +113,7 @@ for queries and aggregations.
.
.
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

## Add data points

Expand All @@ -130,29 +125,29 @@ is an array containing the number of samples in each time series after the opera
If you use the `*` character as the timestamp, Redis will record the current
Unix time, as reported by the server's clock.

<!-- < clients-example time_series_tutorial madd >}} -->
{{< clients-example time_series_tutorial madd >}}
```bash
> TS.MADD thermometer:1 1 9.2 thermometer:1 2 9.9 thermometer:2 2 10.3
1) (integer) 1
2) (integer) 2
3) (integer) 2
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

## Query data points

Use [`TS.GET`]({{< relref "commands/ts.get/" >}}) to retrieve the data point
with the highest timestamp in a time series. This returns both the timestamp and the value.

<!-- < clients-example time_series_tutorial get >}} -->
{{< clients-example time_series_tutorial get >}}
```bash
# The last recorded temperature for thermometer:2
# was 10.3 at time 2ms.
> TS.GET thermometer:2
1) (integer) 2
2) 10.3
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

Use [`TS.RANGE`]({{< relref "commands/ts.range/" >}}) to retrieve data points
from a time series that fall within a given timestamp range. The range is inclusive,
Expand All @@ -162,7 +157,7 @@ indicate the minimum and maximum timestamps in the series. The response is
an array of timestamp-value pairs returned in ascending order by timestamp.
If you want the results in descending order, use [`TS.REVRANGE`]({{< relref "commands/ts.revrange/" >}}) with the same parameters.

<!-- < clients-example time_series_tutorial range >}} -->
{{< clients-example time_series_tutorial range >}}
```bash
# Add 5 data points to a time series named "rg:1".
> TS.CREATE rg:1
Expand Down Expand Up @@ -222,7 +217,7 @@ OK
2) 1) (integer) 0
2) 18
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

Both `TS.RANGE` and `TS.REVRANGE` also let you filter results. Specify
a list of timestamps to include only samples with those exact timestamps
Expand All @@ -231,7 +226,7 @@ use this option). Specify a minimum and maximum value to include only
samples within that range. The value range is inclusive and you can
use the same value for the minimum and maximum to filter for a single value.

<!-- < clients-example time_series_tutorial range_filter >}} -->
{{< clients-example time_series_tutorial range_filter >}}
```bash
> TS.RANGE rg:1 - + FILTER_BY_TS 0 2 4
1) 1) (integer) 0
Expand All @@ -249,7 +244,7 @@ use the same value for the minimum and maximum to filter for a single value.
1) 1) (integer) 2
2) 22
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

### Query multiple time series

Expand All @@ -273,7 +268,7 @@ the presence or value of a label. See the description in the
for details of the filter syntax. You can also request that
data points be returned with all their labels or with a selected subset of them.

<!-- < clients-example time_series_tutorial query_multi >}} -->
{{< clients-example time_series_tutorial query_multi >}}
```bash
# Create three new "rg:" time series (two in the US
# and one in the UK, with different units) and add some
Expand Down Expand Up @@ -372,7 +367,7 @@ OK
3) 1) (integer) 1
2) 18
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

## Aggregation

Expand Down Expand Up @@ -405,7 +400,7 @@ For example, the example below shows an aggregation with the `avg` function over
five data points in the `rg:2` time series. The bucket size is 2ms, so there are three
aggregated values with only one value used to calculate the average for the last bucket.

<!-- < clients-example time_series_tutorial agg >}} -->
{{< clients-example time_series_tutorial agg >}}
```bash
> TS.RANGE rg:2 - + AGGREGATION avg 2
1) 1) (integer) 0
Expand All @@ -415,7 +410,7 @@ aggregated values with only one value used to calculate the average for the last
3) 1) (integer) 4
2) 1.78
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

### Bucket alignment

Expand All @@ -424,7 +419,7 @@ the first bucket in the sequence starts. By default, the reference timestamp is
For example, the following commands create a time series and apply a `min` aggregation
with a bucket size of 25 milliseconds at the default zero alignment.

<!-- < clients-example time_series_tutorial agg_bucket >}} -->
{{< clients-example time_series_tutorial agg_bucket >}}
```bash
> TS.CREATE sensor3
OK
Expand All @@ -444,7 +439,7 @@ OK
3) 1) (integer) 50
2) 5000
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

The diagram below shows the aggregation buckets and their alignment to the reference timestamp
at time zero.
Expand All @@ -460,7 +455,7 @@ Bucket(25ms): |_________________________||_________________________||___________

You can also align the buckets to the start or end of the query range. For example, the following command aligns the buckets to the start of the query range at time 10.

<!-- < clients-example time_series_tutorial agg_align >}} -->
{{< clients-example time_series_tutorial agg_align >}}
```bash
> TS.RANGE sensor3 10 70 AGGREGATION min 25 ALIGN start
1) 1) (integer) 10
Expand All @@ -470,7 +465,7 @@ You can also align the buckets to the start or end of the query range. For examp
3) 1) (integer) 60
2) 6000
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

The diagram below shows this arrangement of buckets.

Expand All @@ -492,7 +487,7 @@ that have the same timestamp and the same label value (this feature is available

For example, the following commands create four time series, two for the UK and two for the US, and add some data points. The first `TS.MRANGE` command groups the results by country and applies a `max` aggregation to find the maximum sample value in each country at each timestamp. The second `TS.MRANGE` command uses the same grouping, but applies an `avg` aggregation.

<!-- < clients-example time_series_tutorial agg_multi >}} -->
{{< clients-example time_series_tutorial agg_multi >}}
```bash
> TS.CREATE wind:1 LABELS country uk
OK
Expand Down Expand Up @@ -558,7 +553,7 @@ OK
3) 1) (integer) 3
2) 13
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

## Compaction

Expand All @@ -580,7 +575,7 @@ only process data that is added to the source series after you create the rule.
For example, you could use the commands below to create a time series along with a
compaction rule to find the minimum reading in each period of 3ms.

<!-- < clients-example time_series_tutorial create_compaction >}} -->
{{< clients-example time_series_tutorial create_compaction >}}
```bash
# The source time series.
> TS.CREATE hyg:1
Expand Down Expand Up @@ -609,14 +604,14 @@ OK
.
.
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

Adding data points within the first 3ms (the first bucket) doesn't
produce any data in the compacted series. However, when you add data for
time 4 (in the second bucket), the compaction rule computes the minimum
value for the first bucket and adds it to the compacted series.

<!-- < clients-example time_series_tutorial comp_add >}} -->
{{< clients-example time_series_tutorial comp_add >}}
```bash
> TS.MADD hyg:1 0 75 hyg:1 1 77 hyg:1 2 78
1) (integer) 0
Expand All @@ -630,7 +625,7 @@ value for the first bucket and adds it to the compacted series.
1) 1) (integer) 0
2) 75
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

The general strategy is that the rule does not add data to the
compaction for the latest bucket in the source series, but will add and
Expand All @@ -649,7 +644,7 @@ that fall within a given timestamp range. The range is inclusive, meaning that
samples whose timestamp equals the start or end of the range are deleted.
If you want to delete a single timestamp, use it as both the start and end of the range.

<!-- < clients-example time_series_tutorial del >}} -->
{{< clients-example time_series_tutorial del >}}
```bash
> TS.INFO thermometer:1
1) totalSamples
Expand Down Expand Up @@ -696,7 +691,7 @@ If you want to delete a single timestamp, use it as both the start and end of th
.
.
```
<!-- < /clients-example >}} -->
{{< /clients-example >}}

## Use time series with other metrics tools

Expand Down