Configuration Parameters

Redis time series support multiple configuration parameters.

Redis Open Source - set configuration parameters

Before Redis 8 in Redis Open Source (version 8.0), all time series configuration parameters are load-time parameters. Use one of the following methods to set the values of load-time configuration parameters:

• Pass them as command-line arguments following the loadmodule argument when starting redis-server:

  redis-server --loadmodule ./{modulename}.so [OPT VAL]...

• Add them as arguments to the loadmodule directive in your configuration file (for example, redis.conf):

  loadmodule ./{modulename}.so [OPT VAL]...

• Use the MODULE LOAD path [arg [arg ...]] command.

• Use the MODULE LOADEX path [CONFIG name value [CONFIG name value ...]] [ARGS args [args ....]] command.

Starting with Redis 8.0, most time series configuration parameters are runtime parameters. While you can set runtime parameters at load time, using the Redis CONFIG command is easier and works the same way as with Redis runtime configuration parameters.

This means:

• CONFIG SET parameter value [parameter value ...]

  Set one or more configuration parameters.

• CONFIG GET parameter [parameter ...]

  Read the current value of one of more parameters.

• CONFIG REWRITE

  Rewrite your Redis configuration file (for example, the redis.conf file) to reflect the configuration changes.

Starting with Redis 8.0, you can specify time series configuration parameters directly in your Redis configuration file the same way you would for Redis configuration parameters.

Once a value is set with CONFIG SET or added manually to your configuration file, it will overwrite values set with --loadmodule, loadmodule, MODULE LOAD, or MODULE LOADEX.

In a cluster, you must run CONFIG SET and CONFIG REWRITE on each node separately.

In Redis 8.0, new names for the time series configuration parameters were introduced to align the naming with the Redis configuration parameters. You must use the new names when using the CONFIG command.

See also Redis configuration.

Time series configuration parameters

Parameter name
(version < 8.0)

Parameter name
(version ≥ 8.0)

Run-time

Redis
Software

Redis
Cloud

CHUNK_SIZE_BYTES

ts-chunk-size-bytes

✅

✅ Supported

✅ Flexible & Annual
❌ Free & Fixed

COMPACTION_POLICY

ts-compaction-policy

✅

✅ Supported

✅ Flexible & Annual
❌ Free & Fixed

DUPLICATE_POLICY

ts-duplicate-policy

✅

✅ Supported

✅ Flexible & Annual
❌ Free & Fixed

RETENTION_POLICY

ts-retention-policy

✅

✅ Supported

✅ Flexible & Annual
❌ Free & Fixed

ENCODING

ts-encoding

✅

✅ Supported

✅ Flexible & Annual
❌ Free & Fixed

IGNORE_MAX_TIME_DIFF

ts-ignore-max-time-diff

✅

IGNORE_MAX_VAL_DIFF

ts-ignore-max-val-diff

✅

NUM_THREADS

ts-num-threads

⬜

✅ Supported

❌ Flexible & Annual
❌ Free & Fixed

OSS_GLOBAL_PASSWORD

Deprecated in v8.0

✅

CHUNK_SIZE_BYTES / ts-chunk-size-bytes

The initial allocation size, in bytes, for the data part of each new chunk. Actual chunks may consume more memory. Changing this value does not affect existing chunks.

Type: integer

Valid range: [48 .. 1048576]; must be a multiple of 8

Precedence order

Because the chunk size can be provided at different levels, the actual precedence of the chunk size is:

1. Key-level policy, as set with TS.CREATE's and TS.ALTER's CHUNK_SIZE optional argument.
2. The ts-chunk-size-bytes configuration parameter.
3. The hard-coded default: 4096

Example

Set the default chunk size to 1024 bytes:

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so CHUNK_SIZE_BYTES 1024

Version >= 8.0:

redis> CONFIG SET ts-chunk-size-bytes 1024

COMPACTION_POLICY / ts-compaction-policy

Default compaction rules for newly created keys with TS.ADD, TS.INCRBY, and TS.DECRBY.

Type: string

Note that this configuration parameter does not affect keys you create with TS.CREATE. To understand why, consider the following scenario: Suppose you define a default compaction policy but then want to manually create an additional compaction rule (using TS.CREATERULE), which requires you to first create an empty destination key (using TS.CREATE). This approach creates a problem: the default compaction policy would cause Redis to automatically create undesired compactions for the destination key.

Each rule is separated by a semicolon (;), the rule consists of multiple fields that are separated by a colon (:):

• Aggregation type: One of the following:

  Aggregator

  Description

  avg

  Arithmetic mean of all values

  sum

  Sum of all values

  min

  Minimum value

  max

  Maximum value

  range

  Difference between the highest and the lowest value

  count

  Number of values

  first

  The value with the lowest timestamp in the bucket

  last

  The value with the highest timestamp in the bucket

  std.p

  Population standard deviation of the values

  std.s

  Sample standard deviation of the values

  var.p

  Population variance of the values

  var.s

  Sample variance of the values

  twa

  Time-weighted average of all values (since v1.8)

• Duration of each time bucket - number and the time representation (Example for one minute: 1M, 60s, or 60000m)

  • m - millisecond
  • s - seconds
  • M - minute
  • h - hour
  • d - day

• Retention time - number and the time representation (Example for one minute: 1M, 60s, or 60000m)

  • m - millisecond
  • s - seconds
  • M - minute
  • h - hour
  • d - day

  0m, 0s, 0M, 0h, or 0d means no expiration.

• (Since v1.8):

  Optional: Time bucket alignment - number and the time representation (Example for one minute: 1M, 60s, or 60000m)

  • m - millisecond
  • s - seconds
  • M - minute
  • h - hour
  • d - day

  Ensure that there is a bucket that starts at exactly alignTimestamp after the Epoch and align all other buckets accordingly. Default value: 0 (aligned with the Epoch). Example: if bucketDuration is 24 hours, setting alignTimestamp to 6h (6 hours after the Epoch) will ensure that each bucket’s timeframe is [06:00 .. 06:00).

Warning:

In a clustered environment, if you set this configuration parameter, you must use hash tags for all time series key names. This ensures that Redis will create each compaction in the same hash slot as its source key. If you don't, the system may fail to compact the data without displaying any error messages.

When a compaction policy is defined, compaction rules are created automatically for newly created time series, and the compaction key name would be:

• If the time bucket alignment is 0:

  key_agg_dur where key is the key of the source time series, agg is the aggregator (in uppercase), and dur is the bucket duration in milliseconds. Example: key_SUM_60000.

• If the time bucket alignment is not 0:

  key_agg_dur_aln where key is the key of the source time series, agg is the aggregator (in uppercase), dur is the bucket duration in milliseconds, and aln is the time bucket alignment in milliseconds. Example: key_SUM_60000_1000.

Precedence order

1. The ts-compaction-policy configuration parameter.
2. No compaction rules.

Example rules

• max:1M:1h - Aggregate using max over one-minute windows and retain the last hour
• twa:1d:0m:360M - Aggregate daily [06:00 .. 06:00) using twa; no expiration

Example

Set a compaction policy composed of 5 compaction rules:

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so COMPACTION_POLICY max:1m:1h;min:10s:5d:10d;last:5M:10m;avg:2h:10d;avg:3d:100d

Version >= 8.0:

redis> CONFIG SET ts-compaction-policy max:1m:1h;min:10s:5d:10d;last:5M:10m;avg:2h:10d;avg:3d:100d

DUPLICATE_POLICY / ts-duplicate-policy

The default policy for handling insertion (TS.ADD and TS.MADD) of multiple samples with identical timestamps, with one of the following values:

policy

description

BLOCK

Ignore any newly reported value and reply with an error

FIRST

Ignore any newly reported value

LAST

Override with the newly reported value

MIN

Only override if the value is lower than the existing value

MAX

Only override if the value is higher than the existing value

SUM

If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

The default value is applied to each new time series upon its creation.

Type: string

Precedence order

Because the duplication policy can be provided at different levels, the actual precedence of the duplication policy is:

1. TS.ADD's ON_DUPLICATE_POLICY optional argument.
2. Key-level policy, as set with TS.CREATE's and TS.ALTER's DUPLICATE_POLICY optional argument.
3. The ts-duplicate-policy configuration parameter.
4. The hard-coded default: BLOCK

RETENTION_POLICY / ts-retention-policy

The default retention period, in milliseconds, for newly created keys.

The retention period is the maximum age of samples compared to the highest reported timestamp, per key. Samples are expired based solely on the difference between their timestamps and the timestamps passed to subsequent TS.ADD, TS.MADD, TS.INCRBY, and TS.DECRBY calls.

Type: integer

Valid range: [0 .. 9,223,372,036,854,775,807]

The value 0 means no expiration.

When both COMPACTION_POLICY / ts-compaction-policy and RETENTION_POLICY / ts-retention-policy are specified, the retention of newly created compactions is according to the retention time specified in COMPACTION_POLICY / ts-compaction-policy.

Precedence order

Because the retention can be provided at different levels, the actual precedence of the retention is:

1. Key-level retention, as set with TS.CREATE's and TS.ALTER's RETENTION optional argument.
2. The ts-retention-policy configuration parameter.
3. No retention.

Example

Set the default retention to 300 days:

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so RETENTION_POLICY 25920000000

Version >= 8.0:

redis> CONFIG SET ts-retention-policy 25920000000

ENCODING / ts-encoding

Note: Before v1.6 this configuration parameter was named CHUNK_TYPE.

Default chunk encoding for automatically created compactions when ts-compaction-policy is configured.

Type: string

Valid values: COMPRESSED, UNCOMPRESSED

Precedence order

1. The ts-encoding configuration parameter.
2. The hard-coded default: COMPRESSED

Example

Set the default encoding to UNCOMPRESSED:

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so ENCODING UNCOMPRESSED

Version >= 8.0:

redis> CONFIG SET ts-encoding UNCOMPRESSED

IGNORE_MAX_TIME_DIFF / ts-ignore-max-time-diff and IGNORE_MAX_VAL_DIFF / ts-ignore-max-val-diff

Default values for newly created keys.

Types:

• ts-ignore-max-time-diff: integer
• ts-ignore-max-val-diff: double

Valid ranges:

• ts-ignore-max-time-diff: [0 .. 9,223,372,036,854,775,807]
• ts-ignore-max-val-diff: [0 .. 1.7976931348623157e+308]

Many sensors report data periodically. Often, the difference between the measured value and the previous measured value is negligible and related to random noise or to measurement accuracy limitations. In such situations it may be preferable not to add the new measurement to the time series.

A new sample is considered a duplicate and is ignored if the following conditions are met:

1. The time series is not a compaction.
2. The time series' ts-duplicate-policy is LAST.
3. The sample is added in-order (timestamp ≥ max_timestamp).
4. The difference of the current timestamp from the previous timestamp (timestamp - max_timestamp) is less than or equal to ts-ignore-max-time-diff.
5. The absolute value difference of the current value from the value at the previous maximum timestamp (abs(value - value_at_max_timestamp) is less than or equal to ts-ignore-max-val-diff.

where max_timestamp is the timestamp of the sample with the largest timestamp in the time series, and value_at_max_timestamp is the value at max_timestamp.

Precedence order

1. The ts-ignore-max-time-diff and ts-ignore-max-val-diff configuration parameters.
2. The hard-coded defaults: 0 and 0.0.

Example

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so IGNORE_MAX_TIME_DIFF 10 IGNORE_MAX_VAL_DIFF 0.1

Version >= 8.0:

redis> CONFIG SET ts-ignore-max-time-diff 10 ts-ignore-max-val-diff 0.1

NUM_THREADS / ts-num-threads

The maximum number of per-shard threads for cross-key queries when using cluster mode (TS.MRANGE, TS.MREVRANGE, TS.MGET, and TS.QUERYINDEX). The value must be equal to or greater than 1. Note that increasing this value may either increase or decrease the performance!

Type: integer

Valid range: [1..16]

Redis Open Source default: 3

Redis Software default: Set by plan, and automatically updates when you change your plan.

Redis Cloud defaults:

• Flexible & Annual: Set by plan
• Free & Fixed: 1

Example

Version < 8.0:

$ redis-server --loadmodule ./redistimeseries.so NUM_THREADS 3

Version >= 8.0:

redis> redis-server --loadmodule ./redistimeseries.so ts-num-threads 3

OSS_GLOBAL_PASSWORD

Prior to version 8.0, when using time series in a cluster, you had to set the OSS_GLOBAL_PASSWORD configuration parameter on all cluster nodes. As of version 8.0, Redis no longer uses this parameter and ignores it if present. Redis now uses a new shared secret mechanism to send internal commands between cluster nodes.

On this page