*Redis CF.INSERT 命令
CF.INSERT 将一个或多个元素添加到 Cuckoo Filter 中，如果过滤器不存在则自动创建。
*语法
CF.INSERT key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Cuckoo Filter 的键名 |
| CAPACITY capacity | Integer | 否 | 新过滤器的期望容量（仅在过滤器不存在时生效） |
| NOCREATE | Flag | 否 | 禁止自动创建过滤器，如果键不存在则返回错误 |
| ITEMS item... | String / Bytes | 是 | 要插入的一个或多个元素 |
*返回值
返回一个整数数组，每个元素对应一个插入操作的结果：
- 1：元素成功插入
- -1：无法插入，因为过滤器已满（需要扩展容量或允许自动扩展）
特殊情况： - Simple error reply：参数数量或类型错误，或者指定了 NOCREATE 但键不存在时返回
*时间复杂度
O(n * (k + i))，其中 n 是元素数量，k 是子过滤器数量，i 是 maxIterations。
*示例
*基本用法（自动创建过滤器）
> CF.INSERT cf CAPACITY 1000 ITEMS item1 item2
1) (integer) 1
2) (integer) 1
*禁止自动创建
> CF.INSERT cf1 CAPACITY 1000 NOCREATE ITEMS item1 item2
(error) ERR not found
*过滤器已满时的插入
> CF.RESERVE cf2 2 BUCKETSIZE 1 EXPANSION 0
OK
> CF.INSERT cf2 ITEMS 1 1 1 1
1) (integer) 1
2) (integer) 1
3) (integer) -1
4) (integer) -1
*批量插入多个元素
> CF.INSERT cf_bulk ITEMS user1 user2 user3 user4 user5
1) (integer) 1
2) (integer) 1
3) (integer) 1
4) (integer) 1
5) (integer) 1
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR wrong number of arguments | 参数数量不足 | 检查是否提供了 ITEMS 和至少一个元素 |
| ERR not found | 指定了 NOCREATE 但键不存在 | 先使用 CF.RESERVE 创建过滤器，或移除 NOCREATE 选项 |
| ERR item exists | 键已存在但不是 Cuckoo Filter 类型 | 使用不同的键名，或删除现有键 |
*最佳实践
- 预创建过滤器：对于已知容量的场景，先用 CF.RESERVE 创建过滤器，避免 CF.INSERT 自动创建时使用默认容量（1024）
- 批量插入：CF.INSERT 支持一次插入多个元素，比多次调用 CF.ADD 更高效
- CAPACITY 与 NOCREATE 互斥：这两个选项不能同时使用，因为 NOCREATE 禁止创建新过滤器
- 处理 -1 返回值：当插入返回 -1 时，说明过滤器已满，可考虑删除并重新创建更大容量的过滤器，或允许自动扩展（设置 EXPANSION > 0）
- 避免重复插入：CF.INSERT 会无条件插入元素，如果需要在元素不存在时才插入，请使用 CF.INSERTNX
*FAQ
Q1: CF.INSERT 和 CF.ADD 有什么区别？ A: CF.INSERT 支持一次插入多个元素，并且可以指定 CAPACITY 和 NOCREATE 选项。CF.ADD 只支持插入单个元素，语法更简洁。CF.INSERT 更适合批量操作场景。
Q2: 如果没有指定 CAPACITY，新过滤器会使用多大容量？ A: 默认容量是 1024。如果预计插入更多元素，建议显式指定 CAPACITY，因为过滤器在接近填满时会自动扩展（如果 EXPANSION > 0），但扩展会带来性能下降和错误率增加。
Q3: 返回 -1 是什么意思？ A: 表示元素无法插入，因为过滤器已满。这通常发生在：1) 容量确实已满；2) EXPANSION 设置为 0 禁止自动扩展；3) 虽然未满但 Cuckoo 交换次数超过 MAXITERATIONS。可以考虑增加容量或调整 MAXITERATIONS。
Q4: CF.INSERT 会覆盖已存在的元素吗？ A: Cuckoo Filter 是概率数据结构，不存储实际元素值，只存储指纹。CF.INSERT 总是尝试插入，不关心元素是否已存在。如果需要在元素不存在时才插入，请使用 CF.INSERTNX。