*Redis TS.ADD 命令
TS.ADD 向时间序列中添加一个数据点（timestamp-value 对）。如果时间序列不存在，可选择自动创建。
*语法
TS.ADD key timestamp value [RETENTION retentionPeriod] [ENCODING [COMPRESSED|UNCOMPRESSED]] [CHUNK_SIZE size] [DUPLICATE_POLICY [BLOCK | FIRST | LAST | MIN | MAX | SUM]] [LABELS {label value} ...] [ON_DUPLICATE policy] [IGNORE ignoreMaxTimediff ignoreMaxValDiff]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | 时间序列键名 |
| timestamp | Integer / String | 是 | 时间戳（毫秒 Unix 时间戳），或 * 表示当前时间 |
| value | Double | 是 | 数据值 |
| RETENTION | Integer | 否 | 数据保留时间（毫秒），0 表示永久保留 |
| ENCODING | Enum | 否 | 编码方式：COMPRESSED（默认）或 UNCOMPRESSED |
| CHUNK_SIZE | Integer | 否 | 每个数据块的大小（字节），默认 4096 |
| DUPLICATE_POLICY | Enum | 否 | 重复时间戳处理策略：BLOCK（报错）、FIRST（忽略）、LAST（覆盖）、MIN（取最小）、MAX（取最大）、SUM（累加） |
| LABELS | List | 否 | 标签键值对，用于 TS.MGET / TS.MRANGE 查询 |
| ON_DUPLICATE | Enum | 否 | 同 DUPLICATE_POLICY（别名） |
| IGNORE | List | 否 | 忽略时间差和值差范围内的重复数据 |
*返回值
- Integer：成功添加的时间戳
- Error：参数错误、键类型不匹配、重复策略冲突等
*时间复杂度
O(1)（已存在时间序列）
*示例
*基本用法
> TS.ADD temperature:room1 1625232000000 23.5
(integer) 1625232000000
*使用当前时间
> TS.ADD temperature:room1 * 24.0
(integer) 1625235000000
*自动创建时间序列（带标签）
> TS.ADD temperature:room2 1625232000000 22.0 RETENTION 86400000 LABELS sensor temp room 2
(integer) 1625232000000
*处理重复时间戳
> TS.ADD temperature:room1 1625232000000 25.0 ON_DUPLICATE LAST
(integer) 1625232000000
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| TSDB: Error at add, update is not supported in BLOCK duplicate policy | 重复时间戳且策略为 BLOCK | 使用 LAST 或 SUM 策略，或删除旧数据 |
| WRONGTYPE | key 已存在且不是时间序列 | 使用正确 key 名，或删除旧 key |
| ERR wrong number of arguments | 参数不足 | 检查 key、timestamp、value 是否齐全 |
| TSDB: The timestamp is older than the retention | 时间戳超出保留窗口 | 调整 RETENTION 或检查时间戳 |
*最佳实践
- 使用
*自动获取当前时间戳，避免客户端时间偏差 - 明确设置 DUPLICATE_POLICY，避免默认 BLOCK 导致写入失败
- 合理设置 RETENTION，避免无限增长占用内存
- 使用 LABELS 便于后续 TS.MGET / TS.MRANGE 批量查询
- 批量写入优先使用 TS.MADD，减少 RTT
*FAQ
Q1: TS.ADD 和 TS.MADD 有什么区别？ A: TS.ADD 写入单个数据点，支持自动创建和更多参数；TS.MADD 批量写入多个数据点，性能更高。
Q2: 重复时间戳怎么处理？ A: 通过 DUPLICATE_POLICY 控制，推荐 LAST（覆盖）或 SUM（累加），根据业务场景选择。
Q3: 时间戳精度是什么？ A: 毫秒级 Unix 时间戳（13 位数字）。