*Redis TDIGEST.ADD 命令

TDIGEST.ADD 将一个或多个观测值添加到指定的 t-digest 数据结构中。

---

*语法

TDIGEST.ADD key value [value ...]

---

*参数说明

参数	类型	必填	说明
key	String	是	t-digest 键名
value	Double	是	要添加的观测值，支持一次添加多个

---

*返回值

• OK：所有值添加成功
• Error：key 不存在或类型错误、参数错误

---

*时间复杂度

O(N)，N 为单次添加的观测值数量。每个值的添加为 O(1)。

---

*示例

*基本用法

> TDIGEST.CREATE temp
OK
> TDIGEST.ADD temp 15.2
OK
> TDIGEST.ADD temp 18.5 20.0 22.3
OK

*批量添加数据点

> TDIGEST.CREATE latency
OK
> TDIGEST.ADD latency 12 15 18 21 25 30 35 40 45 50
OK
> TDIGEST.INFO latency
 1) "Compression"
 2) "100"
 3) "Capacity"
 4) (integer) 610
 5) "Merged nodes"
 6) (integer) 7
 7) "Unmerged nodes"
 8) (integer) 0
 9) "Total compressions"
10) (integer) 1
11) "Memory usage"
12) (integer) 1856
13) "Observations"
14) (integer) 10

*添加负数和浮点数

> TDIGEST.CREATE scores
OK
> TDIGEST.ADD scores -5.5 0 3.14 99.99
OK
> TDIGEST.MIN scores
"-5.5"
> TDIGEST.MAX scores
"99.99"

---

*常见错误

错误	原因	解决
ERR wrong number of arguments	未提供 key 或 value	至少提供一个 key 和一个 value
ERR key does not exist	key 不存在，且未预先创建	先用 TDIGEST.CREATE 创建
WRONGTYPE Operation against a key holding the wrong kind of value	key 不是 t-digest 类型	确认 key 未被其他数据结构占用
ERR value is not a valid float	value 不是有效浮点数	检查输入格式

---

*最佳实践

• 预先创建：建议先用 TDIGEST.CREATE 创建数据结构，再执行 ADD
• 批量添加：一次 ADD 多个值比多次单值 ADD 更高效
• 数据预热：统计场景下可先批量 ADD 历史数据，再实时增量添加
• 监控内存：大量数据点会增加内存占用，可通过 TDIGEST.INFO 监控

---

*FAQ

Q1: 可以直接 ADD 到一个不存在的 key 吗？ A: 不可以。必须先执行 TDIGEST.CREATE 创建 t-digest 结构，否则返回 key does not exist 错误。

Q2: 添加重复值会影响统计结果吗？ A: 会。所有值（包括重复值）都会被纳入 t-digest 的统计计算中，影响分位数、排名等指标。

Q3: 单次 ADD 最多可以添加多少个值？ A: 没有硬性上限，但建议根据内存和性能需求合理控制单次数量。大量值建议分批添加。