TS.CREATERULE

{{< note >}} This command's behavior varies in clustered Redis environments. See the [multi-key operations]({{< relref "/develop/using-commands/multi-key-operations" >}}) page for more information. {{< /note >}}

Create a compaction rule

Examples

Required arguments

<details open><summary><code>sourceKey</code></summary>

is key name for the source time series.

</details> <details open><summary><code>destKey</code></summary>

is key name for destination (compacted) time series. It must be created before TS.CREATERULE is called.

</details> <details open><summary><code>AGGREGATION aggregator bucketDuration</code></summary>

aggregates results into time buckets.

• 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.

<note><b>Notes</b>

• Only new samples that are added into the source series after the creation of the rule will be aggregated.
• Calling TS.CREATERULE with a nonempty destKey may result in inconsistencies between the raw and the compacted data.
• Explicitly adding samples to a compacted time series (using [TS.ADD]({{< relref "commands/ts.add/" >}}), [TS.MADD]({{< relref "commands/ts.madd/" >}}), [TS.INCRBY]({{< relref "commands/ts.incrby/" >}}), or [TS.DECRBY]({{< relref "commands/ts.decrby/" >}})) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.
• If no samples are added to the source time series during a bucket period. no compacted sample is added to the destination time series.
• The timestamp of a compacted sample added to the destination time series is set to the start timestamp the appropriate compaction bucket. For example, for a 10-minute compaction bucket with no alignment, the compacted samples timestamps are x:00, x:10, x:20, and so on.
• Deleting destKey will cause the compaction rule to be deleted as well.

{{% warning %}} In a clustered environment, you must use [hash tags]({{< relref "/operate/oss_and_stack/reference/cluster-spec" >}}#hash-tags) to force sourceKey and destKey to be stored in the same hash slot. If you don't, Redis may fail to compact the data without displaying any error messages. {{% /warning %}}

</note>

Optional arguments

<details open><summary><code>alignTimestamp</code> (since RedisTimeSeries 1.8)</summary>

ensures that there is a bucket that starts exactly at alignTimestamp and aligns all other buckets accordingly. It is expressed in milliseconds. The default value is 0: aligned with the Unix epoch.

For example, if bucketDuration is 24 hours (24 * 3600 * 1000), setting alignTimestamp to 6 hours after the Unix epoch (6 * 3600 * 1000) ensures that each bucket’s timeframe is [06:00 .. 06:00).

</details>

Examples

<details open> <summary><b>Create a compaction rule</b></summary>

Create a time series to store the temperatures measured in Tel Aviv.

{{< highlight bash >}} 127.0.0.1:6379> TS.CREATE temp:{TLV} LABELS type temp location TLV OK {{< / highlight >}}

Next, create a compacted time series named dailyAvgTemp containing one compacted sample per 24 hours: the time-weighted average of all measurements taken from midnight to next midnight.

{{< highlight bash >}} 127.0.0.1:6379> TS.CREATE dailyAvgTemp:{TLV} LABELS type temp location TLV 127.0.0.1:6379> TS.CREATERULE temp:{TLV} dailyAvgTemp:{TLV} AGGREGATION twa 86400000 {{< / highlight >}}

Now, also create a compacted time series named dailyDiffTemp. This time series will contain one compacted sample per 24 hours: the difference between the minimum and the maximum temperature measured between 06:00 and 06:00 next day. Here, 86400000 is the number of milliseconds in 24 hours, 21600000 is the number of milliseconds in 6 hours.

{{< highlight bash >}} 127.0.0.1:6379> TS.CREATE dailyDiffTemp:{TLV} LABELS type temp location TLV 127.0.0.1:6379> TS.CREATERULE temp:{TLV} dailyDiffTemp:{TLV} AGGREGATION range 86400000 21600000 {{< / highlight >}}

</details>

Redis Software and Redis Cloud compatibility

| 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> | |

Return information

{{< multitabs id="ts-createrule-return-info" tab1="RESP2" tab2="RESP3" >}}

One of the following:

• [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): OK when the compaction rule is created successfully.
• [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: invalid arguments, wrong key type, sourceKey does not exist, destKey does not exist, sourceKey is already a destination of a compaction rule, destKey is already a source or a destination of a compaction rule, or sourceKey and destKey are identical.

-tab-sep-

One of the following:

• [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): OK when the compaction rule is created successfully.
• [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: invalid arguments, wrong key type, sourceKey does not exist, destKey does not exist, sourceKey is already a destination of a compaction rule, destKey is already a source or a destination of a compaction rule, or sourceKey and destKey are identical.

{{< /multitabs >}}

See also

[TS.DELETERULE]({{< relref "commands/ts.deleterule/" >}})

Related topics

[RedisTimeSeries]({{< relref "/develop/data-types/timeseries/" >}})