TS.ADD

Syntax
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

向时间序列添加一个样本

示例

必需的参数

key

是时间序列的键名。

timestamp

是Unix时间（整数，以毫秒为单位），指定样本时间戳或*以将样本时间戳设置为服务器时钟的Unix时间。

Unix时间是自1970年1月1日00:00:00 UTC（Unix纪元）以来经过的毫秒数，不考虑闰秒的调整。

value

是样本的（双精度）数值数据值。双精度数字应遵循RFC 7159（JSON标准）。特别是，解析器会拒绝不适合二进制64的过大值。它不接受NaN或无限值。

备注:

  • 当指定的键不存在时，将创建一个新的时间序列。

    如果定义了COMPACTION_POLICY配置参数，也会创建压缩的时间序列。

  • 如果 timestamp 与现有最大时间戳相比超过了保留期限，样本将被丢弃并返回错误。

  • 当向定义了压缩规则的时间序列添加样本时：

    • 如果受影响聚合时间段的原始样本都可用，则根据报告的样本和原始样本重新计算压缩值。
    • 如果由于时间序列保留策略导致的修剪，只有受影响聚合时间段的部分原始样本可用，则根据报告的样本和可用的原始样本重新计算压缩值。
    • 如果由于时间序列保留策略导致的修剪，受影响聚合时间段的原始样本不可用，则不更新压缩值时间段。

  • 显式地向压缩的时间序列添加样本（使用TS.ADD、TS.MADD、TS.INCRBY或TS.DECRBY）可能会导致原始数据和压缩数据之间的不一致。压缩过程可能会覆盖这些样本。

可选参数

以下参数是可选的，因为它们可以通过TS.CREATE设置。

RETENTION retentionPeriod

是最大保留期限，与现有的最大时间戳相比，以毫秒为单位。

仅当您创建新的时间序列时使用它。如果您正在向现有时间序列添加样本，则忽略此选项。请参阅TS.CREATE中的RETENTION。

ENCODING enc

指定系列样本的编码格式。

仅当您创建新的时间序列时使用它。如果您正在向现有时间序列添加样本，则忽略此选项。请参阅TS.CREATE中的ENCODING。

CHUNK_SIZE size

是分配给每个数据块的内存大小，以字节为单位。

仅当您创建新的时间序列时使用它。如果您正在向现有时间序列添加样本，则忽略此选项。请参阅TS.CREATE中的CHUNK_SIZE。

DUPLICATE_POLICY policy

是处理具有相同时间戳的多个样本插入（TS.ADD 和 TS.MADD）的策略。

仅当您创建新的时间序列时使用它。如果您正在向现有时间序列添加样本，则忽略此选项。请参阅TS.CREATE中的DUPLICATE_POLICY。

ON_DUPLICATE policy_ovr

覆盖键和数据库配置用于DUPLICATE_POLICY，处理具有相同时间戳的样本的策略。 此覆盖仅对此单个命令有效，并不设置时间序列重复策略（可以使用TS.ALTER设置）。

policy_ovr 可以是以下值之一：

  • BLOCK: 忽略任何新报告的值并回复错误
  • FIRST: 忽略任何新报告的值
  • LAST: 使用新报告的值进行覆盖
  • MIN: 仅当值低于现有值时覆盖
  • MAX: 仅当值高于现有值时才覆盖
  • SUM: 如果存在先前的样本，则将新样本添加到其中，以便更新后的值设置为（先前 + 新）。如果不存在先前的样本，则值设置为新值。

当通过此命令创建新的时间序列时，此参数无效。

IGNORE ignoreMaxTimediff ignoreMaxValDiff

是处理重复样本的策略。如果满足以下条件，新样本将被视为重复并被忽略：

  • 时间序列不是压缩的；
  • 时间序列的 DUPLICATE_POLICY 是 LAST;
  • 样本按顺序添加（timestamp ≥ max_timestamp）；
  • 当前时间戳与前一个时间戳的差值（timestamp - max_timestamp）小于或等于IGNORE_MAX_TIME_DIFF；
  • 当前值与上一个最大时间戳处的值的绝对差值（abs(value - value_at_max_timestamp）小于或等于IGNORE_MAX_VAL_DIFF。

其中 max_timestamp 是时间序列中具有最大时间戳的样本的时间戳，而 value_at_max_timestamp 是 max_timestamp 处的值。

当未指定时：设置为全局的IGNORE_MAX_TIME_DIFF和IGNORE_MAX_VAL_DIFF，默认情况下，两者都设置为0。

这些参数在创建新的时间序列时用于设置每个键的参数，并且在调用现有时间序列时会被忽略（使用现有的每个键配置参数）。

LABELS {label value}...

是一组标签-值对，表示时间序列的元数据标签。

仅当您创建新的时间序列时使用它。如果您正在向现有时间序列添加样本，则忽略它。请参阅TS.CREATE中的LABELS。

备注:

  • 您可以使用此命令创建一个新的时间序列，并在一个命令中向其添加数据。 RETENTION, ENCODING, CHUNK_SIZE, DUPLICATE_POLICY, IGNORE, 和 LABELS 仅在创建新的时间序列时使用，在向现有时间序列添加样本时会被忽略。
  • 设置RETENTION和LABELS会引入额外的时间复杂度。

返回值

返回以下回复之一：

  • Integer reply - 插入样本的时间戳。如果样本被忽略（参见TS.CREATE中的IGNORE），回复将是时间序列中的最大时间戳。
  • [] 在错误情况下（无效参数、错误的键类型等），当重复策略为 BLOCK 时，或者当 timestamp 比最大现有时间戳早于保留期时

复杂性

如果时间序列上存在压缩规则，TS.ADD 的性能可能会降低。 TS.ADD 的复杂度始终为 O(M)，其中 M 是压缩规则的数量，或者在没有压缩时为 O(1)。

示例

Append a sample to a temperature time series

创建一个温度时间序列，设置其保留时间为1年，并附加一个样本。

127.0.0.1:6379> TS.ADD temperature:3:11 1548149183000 27 RETENTION 31536000000
(integer) 1548149183000

注意： 如果已经存在具有此名称的时间序列，样本将被添加，但保留时间不会改变。

向时间序列添加一个样本，将样本的时间戳设置为服务器时钟的当前Unix时间。

127.0.0.1:6379> TS.ADD temperature:3:11 * 30
(integer) 1662042954573

另请参阅

TS.CREATE

RedisTimeSeries


RATE THIS PAGE
Back to top ↑