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 ...]]
适用版本
Redis Open Source / TimeSeries 1.0.0
时间复杂度
当 M 是压缩规则的数量时为 O(M)，没有压缩时为 O(1)
ACL 类别
@timeseries， @write， @slow，

向时间序列附加一个样本

示例

必需参数

key

是时间序列的键名。

timestamp

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

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

value

是样本的（双精度浮点数）数值。该双精度浮点数应遵循 RFC 7159 (JSON 标准)。特别是，解析器会拒绝超出 binary64 范围的过大值。它不接受 NaN 或无穷大值。

注意事项

  • 如果指定的键不存在，则会创建一个新的时间序列。

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

  • 如果 timestamp 相对于现有最大时间戳早于保留期，则丢弃该样本并返回错误。

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

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

  • 将样本显式添加到压缩时间序列（使用 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 会引入额外的时间复杂度。

返回值

返回以下回复之一

  • 整数回复 - 插入或更新样本的时间戳。如果样本被忽略（请参阅 TS.CREATE 中的 IGNORE），则回复将是时间序列中的最大时间戳。
  • 出现错误时（参数无效、键类型错误等）、重复策略为 BLOCK 时，或当 timestamp 相对于现有最大时间戳早于保留期时，返回 []。

复杂度

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

示例

向温度时间序列附加样本

创建一个温度时间序列，将其保留期设置为 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


评价本页
返回顶部 ↑
© . This site is unofficial and not affiliated with Redis, Inc.