TS.ADD
TS.ADD key timestamp value [RETENTION retentionPeriod] [ENCODING <COMPRESSED|UNCOMPRESSED>] [CHUNK_SIZE size] [DUPLICATE_POLICY policy] [ON_DUPLICATE policy_ovr] [IGNORE ignoreMaxTimediff ignoreMaxValDiff] [LABELS [label value ...]]
- Available in:
- Redis Stack / TimeSeries 1.0.0
- Time complexity:
- O(M) when M is the amount of compaction rules or O(1) with no compaction
Append a sample to a time series
Required arguments
key
is key name for the time series.
timestamp
is Unix time (integer, in milliseconds) specifying the sample timestamp or *
to set the sample timestamp to the Unix time of the server's clock.
Unix time is the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch, without adjustments made due to leap seconds.
value
is (double) numeric data value of the sample. The double number should follow RFC 7159 (JSON standard). In particular, the parser rejects overly large values that do not fit in binary64. It does not accept NaN or infinite values.
-
When specified key does not exist, a new time series is created.
if a COMPACTION_POLICY configuration parameter is defined, compacted time series would be created as well.
-
If
timestamp
is older than the retention period compared to the maximum existing timestamp, the sample is discarded and an error is returned. -
When adding a sample to a time series for which compaction rules are defined:
- If all the original samples for an affected aggregated time bucket are available, the compacted value is recalculated based on the reported sample and the original samples.
- If only a part of the original samples for an affected aggregated time bucket is available due to trimming caused in accordance with the time series RETENTION policy, the compacted value is recalculated based on the reported sample and the available original samples.
- If the original samples for an affected aggregated time bucket are not available due to trimming caused in accordance with the time series RETENTION policy, the compacted value bucket is not updated.
-
Explicitly adding samples to a compacted time series (using
TS.ADD
,TS.MADD
,TS.INCRBY
, orTS.DECRBY
) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.
Optional arguments
The following arguments are optional because they can be set by TS.CREATE
.
RETENTION retentionPeriod
is maximum retention period, compared to the maximum existing timestamp, in milliseconds.
Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See RETENTION
in TS.CREATE
.
ENCODING enc
specifies the series sample encoding format.
Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See ENCODING
in TS.CREATE
.
CHUNK_SIZE size
is memory size, in bytes, allocated for each data chunk.
Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See CHUNK_SIZE
in TS.CREATE
.
DUPLICATE_POLICY policy
is policy for handling insertion (TS.ADD
and TS.MADD
) of multiple samples with identical timestamps.
Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See DUPLICATE_POLICY
in TS.CREATE
.
ON_DUPLICATE policy_ovr
is overwrite key and database configuration for DUPLICATE_POLICY, the policy for handling samples with identical timestamps.
This override is effective only for this single command and does not set the time series duplication policy (which can be set with TS.ALTER
).
policy_ovr
can be one of the following values:
BLOCK
: ignore any newly reported value and reply with an errorFIRST
: ignore any newly reported valueLAST
: override with the newly reported valueMIN
: only override if the value is lower than the existing valueMAX
: only override if the value is higher than the existing valueSUM
: If a previous sample exists, add the new sample to it so that the updated value is set to (previous + new). If no previous sample exists, the value is set to the new value.
This argument has no effect when a new time series is created by this command.
IGNORE ignoreMaxTimediff ignoreMaxValDiff
is the policy for handling duplicate samples. A new sample is considered a duplicate and is ignored if the following conditions are met:
- The time series is not a compaction;
- The time series'
DUPLICATE_POLICY
ISLAST
; - The sample is added in-order (
timestamp ≥ max_timestamp
); - The difference of the current timestamp from the previous timestamp (
timestamp - max_timestamp
) is less than or equal toIGNORE_MAX_TIME_DIFF
; - 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 toIGNORE_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
.
When not specified: set to the global IGNORE_MAX_TIME_DIFF and IGNORE_MAX_VAL_DIFF, which are, by default, both set to 0.
These parameters are used when creating a new time series to set the per-key parameters, and are ignored when called with an existing time series (the existing per-key configuration parameters is used).
LABELS {label value}...
is set of label-value pairs that represent metadata labels of the time series.
Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See LABELS
in TS.CREATE
.
- You can use this command to create a new time series and add data to it in a single command.
RETENTION
,ENCODING
,CHUNK_SIZE
,DUPLICATE_POLICY
,IGNORE
, andLABELS
are used only when creating a new time series, and ignored when adding samples to an existing time series. - Setting
RETENTION
andLABELS
introduces additional time complexity.
Return value
Returns one of these replies:
- Integer reply - the timestamp of the upserted sample. If the sample is ignored (See
IGNORE
inTS.CREATE
), the reply will be the largest timestamp in the time series. - [] on error (invalid arguments, wrong key type, etc.), when duplication policy is
BLOCK
, or whentimestamp
is older than the retention period compared to the maximum existing timestamp
Complexity
If a compaction rule exists on a time series, the performance of TS.ADD
can be reduced.
The complexity of TS.ADD
is always O(M)
, where M
is the number of compaction rules or O(1)
with no compaction.
Examples
Append a sample to a temperature time series
Create a temperature time series, set its retention to 1 year, and append a sample.
127.0.0.1:6379> TS.ADD temperature:3:11 1548149183000 27 RETENTION 31536000000
(integer) 1548149183000
Add a sample to the time series, setting the sample's timestamp to the current Unix time of the server's clock.
127.0.0.1:6379> TS.ADD temperature:3:11 * 30
(integer) 1662042954573