*Redis TOPK.ADD 命令
TOPK.ADD 向 Top-K 结构中添加一个或多个元素。
*语法
TOPK.ADD key item [item ...]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Top-K 结构键名 |
| item | String / Bytes | 是 | 要添加的元素，支持多个 |
*返回值
- Array：对每个添加的元素，返回被挤出 Top-K 列表的元素名；若未挤出任何元素，返回空字符串
*时间复杂度
O(k × depth)，k 为 Top-K 容量，depth 为结构深度。单个元素为 O(depth)。
*示例
*添加单个元素
> TOPK.RESERVE mytopk 3 100 5 0.9
OK
> TOPK.ADD mytopk apple
1) ""
*添加多个元素
> TOPK.ADD mytopk banana cherry date
1) ""
2) ""
3) ""
*观察元素被挤出
> TOPK.ADD mytopk apple apple apple banana
1) ""
2) ""
3) "date"
4) ""
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR wrong number of arguments | 缺少 key 或 item | 确保至少传入 key 和一个 item |
| WRONGTYPE | key 不是 Top-K 类型 | 确认 key 由 TOPK.RESERVE 创建 |
| ERR key does not exist | Top-K 结构不存在 | 先用 TOPK.RESERVE 初始化 |
*最佳实践
- 适用场景：实时流数据中的高频元素统计，如热门搜索词、高频访问 IP
- 批量添加元素可减少网络往返，提升吞吐量
- 配合 TOPK.QUERY 可快速判断元素是否在当前 Top-K 列表中
- 高频元素被挤出时，返回值会显示被挤出的元素名，可用于审计或降级通知
*FAQ
Q1: TOPK.ADD 返回空字符串是什么意思？ A: 表示添加该元素后，没有元素被挤出 Top-K 列表，当前元素仍在列表内或尚未进入列表。
Q2: 可以添加重复的元素吗？ A: 可以，重复添加同一元素会增加其计数权重，提高在 Top-K 中的排名。
Q3: 如何判断一个元素是否成功进入 Top-K？ A: 使用 TOPK.QUERY 命令查询该元素，返回 1 表示在列表中，0 表示不在。