TS.ADD

将样本附加到时间序列中

语法

TS.ADD key timestamp value [RETENTION retentionPeriod] [ENCODING ] [CHUNK SIZE size] [ON DUPLICATE ] [LABELS label value [label value ...]]

引入版本：1.0.0

复杂度摘要：O(M)

将样本附加到时间序列中

示例

必需参数

key

是时间序列的键名称。

timestamp

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

Unix 时间是自 1970 年 1 月 1 日（Unix 纪元）UTC 00:00:00 起经过的毫秒数，没有因闰秒而进行调整。

value

是样本的（双精度）数值数据值。双数应遵循RFC 7159（JSON标准）。特别是，解析器会拒绝不适合 binary64 的过大值。它不接受无限值。从 Redis 8.6 开始支持 NaN（非数字）值。

Notes: - When specified key does not exist, a new time series is created.

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

  • 如果与最大现有时间戳相比，timestamp 早于保留期，则丢弃样本并返回错误。
  • 将样本添加到定义了压缩规则的时间序列中时：
  • 如果受影响聚合时间桶的所有原始样本均可用，则根据报告样本和原始样本重新计算压缩值。
  • 如果由于根据时间序列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：如果存在先前的样本，则添加新样本，以便更新后的值设置为（前一个 + 新）。如果不存在先前的样本，则该值将设置为新值。

NaN Handling (Redis 8.6+): When using MIN, MAX, or SUM policies, an error is returned if there is an existing value in the specified timestamp and either the previous or the new value (but not both) are NaN.

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

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。

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

NaN Handling (Redis 8.6+): NaN values are never regarded as duplicates when using the IGNORE parameters.

LABELS {label value}...

是表示时间序列的元数据标签的标签值对的集合。

仅当您要创建新时间序列时才使用它。如果您将样本添加到现有时间序列中，它将被忽略。请参阅 TS.CREATE 中的 LABELS。

Notes: - 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, and LABELS are used only when creating a new time series, and ignored when adding samples to an existing time series. - Setting RETENTION and LABELS introduces additional time complexity.

复杂性

如果时间序列上存在压缩规则，则会降低 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 温度:3:11 1548149183000 27 保留 31536000000 (整数) 1548149183000

Note: If a time series with such a name already exists, the sample is added, but the retention does not change.

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

127.0.0.1:6379> TS.ADD 温度:3:11 * 30 (整数) 1662042954573

Redis Software 与 Redis Cloud 兼容性

Redis
软件		 Redis
Cloud		 说明
✅ 支持
 ✅ 灵活且每年一次
✅ 免费和固定

返回值

RESP2

以下之一： * 整数回复：更新插入的样本的时间戳。如果样本被忽略（参见TS.CREATE中的IGNORE），则回复将是时间序列中最大的时间戳。 * 简单错误回复 在这些情况下：无效的参数、错误的键类型、重复策略为 BLOCK，或者当 timestamp 比最大现有时间戳早于保留期时。

RESP3

以下之一： * 整数回复：更新插入的样本的时间戳。如果样本被忽略（参见TS.CREATE中的IGNORE），则回复将是时间序列中最大的时间戳。 * 简单错误回复 在这些情况下：无效的参数、错误的键类型、重复策略为 BLOCK，或者当 timestamp 比最大现有时间戳早于保留期时。

参见

TS.CREATE

Redis时间系列

资料来源：Redis 官方 TS.ADD 文档；中文内容参考 Redis 文档许可。