*Redis CMS.INCRBY 命令
CMS.INCRBY 将 Count-Min Sketch 中一个或多个 item 的计数增加指定增量。
*语法
CMS.INCRBY key item increment [item increment ...]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Sketch 的键名 |
| item | String | 是 | 要增加计数的 item |
| increment | Integer | 是 | 增加的量（正数或负数） |
*返回值
- Array of Integers：返回数组，每个元素对应一个 item 更新后的最小计数值（min-count）
- Error：参数错误、键不存在、键类型错误，或计数器溢出
*时间复杂度
O(n)，其中 n 是 item 的数量
*示例
*增加单个 item 计数
> CMS.INITBYDIM test 2000 5
OK
> CMS.INCRBY test foo 10
1) (integer) 10
*批量增加多个 item 计数
> CMS.INCRBY test foo 10 bar 42
1) (integer) 20
2) (integer) 42
*多次增加同一 item
> CMS.INCRBY test foo 5
1) (integer) 25
> CMS.QUERY test foo
1) (integer) 25
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR wrong number of arguments | item 和 increment 未成对 | 确保每个 item 都有对应的 increment |
| ERR key does not exist | key 不存在 | 先用 CMS.INITBYDIM 或 CMS.INITBYPROB 初始化 |
| WRONGTYPE | key 不是 CMS 类型 | 确认 key 正确，或重新初始化 |
| ERR overflow | 计数器溢出 | 减少增量或增大 sketch 的 width/depth |
*最佳实践
- 批量增加优于多次单条调用，减少网络往返
- 增量可正可负，但注意计数器不能低于 0（会返回 0）
- 频繁写入同一 sketch 时，关注 sketch 的内存占用和性能
- 计数器最大值为 64 位有符号整数，注意避免溢出
*FAQ
Q1: CMS.INCRBY 可以传入负数吗？ A: 可以，但计数器值不会低于 0。如果减去的量超过当前计数，结果会返回 0。
Q2: 返回的 min-count 是什么？ A: 由于 Count-Min Sketch 对每个 item 使用多个计数器，返回的是所有对应计数器中的最小值，这是最接近真实计数的估计值。
Q3: 为什么计数器会溢出？ A: CMS 使用 64 位有符号整数计数器。如果 sketch 的 width/depth 过小，高频 item 的计数器可能超过最大值。增大 width 或 depth 可避免。