*Redis CF.ADD 命令
CF.ADD 将单个元素添加到 Cuckoo Filter 中。若 key 不存在则自动创建。
*语法
CF.ADD key item
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Cuckoo Filter 的键名 |
| item | String / Bytes | 是 | 要添加的元素 |
*返回值
- 1：添加成功
- Error：键存在但非 Cuckoo Filter 类型，或内部循环踢出（cuckoo cycle）次数过多导致插入失败
*时间复杂度
O(n)，n 为哈希桶数量相关常数。通常接近 O(1)。
*示例
*基本用法
> CF.ADD mycf "user123"
(integer) 1
> CF.ADD mycf "user123"
(integer) 1
> CF.COUNT mycf "user123"
(integer) 2
*自动创建过滤器
> CF.ADD auto_cf "item1"
(integer) 1
> CF.INFO auto_cf
1) "Size"
2) (integer) 512
...
*插入失败（过滤器过满）
> CF.RESERVE full_cf 1000
OK
> CF.ADD full_cf "a" -- 重复插入至满
...
> CF.ADD full_cf "newitem"
(error) ERR key is full
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| WRONGTYPE | key 已存在且不是 Cuckoo Filter 类型 | 确认 key 未被其他数据结构占用 |
| ERR key is full | 过滤器已满且无法踢出空间 | 重建更大容量的过滤器，或使用 CF.RESERVE 预留更大容量 |
*最佳实践
- Cuckoo Filter 支持删除（CF.DEL），但需要确认元素确实已存在。适合需要删除操作的场景
- 容量不足时可能触发内部元素迁移（cuckoo kicking），性能会下降
- 生产环境建议先用 CF.RESERVE 创建过滤器，避免自动创建的默认参数不符合需求
*FAQ
Q1: CF.ADD 添加重复元素会怎样？ A: 返回 1（成功），Cuckoo Filter 会记录重复次数。可用 CF.COUNT 查看某个元素的计数。
Q2: 和 BF.ADD 有什么区别？ A: Cuckoo Filter 支持删除（CF.DEL）和计数（CF.COUNT），而 Bloom Filter 不支持。但 Cuckoo Filter 在接近满容量时可能出现插入失败。
Q3: 插入失败（key is full）怎么办？ A: 说明过滤器已满且无法再踢出空间。需创建容量更大的新过滤器，将元素迁移过去。