*Redis TOPK.INCRBY 命令
TOPK.INCRBY 将 Top-K 结构中指定元素的计数增加指定的整数值。
*语法
TOPK.INCRBY key item increment [item increment ...]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Top-K 结构键名 |
| item | String / Bytes | 是 | 要增加计数的元素 |
| increment | Integer | 是 | 增加的计数值，支持负数 |
*返回值
- Array：对每个 item，返回被挤出 Top-K 列表的元素名；若未挤出任何元素，返回空字符串
*时间复杂度
O(k × depth × M)，M 为 item-increment 对数。单个元素为 O(k × depth)。
*示例
*单个元素增加计数
> TOPK.RESERVE mytopk 3 100 5 0.9
OK
> TOPK.INCRBY mytopk apple 5
1) ""
> TOPK.COUNT mytopk apple
(integer) 5
*批量增加计数
> TOPK.INCRBY mytopk banana 3 cherry 2 date 1
1) ""
2) ""
3) ""
*观察元素被挤出
> TOPK.INCRBY mytopk fig 10
1) "date"
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR wrong number of arguments | item 和 increment 未成对 | 确保每对 item-increment 完整 |
| ERR increment is not an integer | increment 不是整数 | 传入整数值 |
| WRONGTYPE | key 不是 Top-K 类型 | 确认 key 由 TOPK.RESERVE 创建 |
| ERR key does not exist | Top-K 结构不存在 | 先用 TOPK.RESERVE 初始化 |
*最佳实践
- 适用场景：需要按权重增加元素频率的场景，如用户评分加权、流量按字节数统计
- 支持负值 increment，可用于递减或纠错场景
- 批量操作可减少网络往返，提升写入性能
- 与 TOPK.ADD 的区别：ADD 每次只增加 1，INCRBY 可自定义增量值
*FAQ
Q1: TOPK.INCRBY 和 TOPK.ADD 有什么区别？ A: TOPK.ADD 每次对元素计数 +1；TOPK.INCRBY 可以按指定数值增减，适合加权统计。
Q2: increment 可以是负数吗？ A: 可以，负值会减少元素计数。但如果计数归零，元素不会立即从 Top-K 中移除，需由新元素挤出。
Q3: 返回的被挤出元素是输入的元素吗？ A: 不一定。返回的是因当前增量操作导致排名下降而被挤出 Top-K 列表的其他元素。