Redis 命令及数据类型 -- CF(Cuckoo Filter)

发表于 2025-12-22 分类于技术， redis

阅读次数：本文字数： 1.9k 阅读时长 ≈ 7 分钟

摘要

本文介绍 Redis 扩展模型 RedisBloom 中的 Cuckoo Filter 数据类型
本文基于redis-7.4.7，springboot-3.5.8
Redis官网：https://redis.io/
Redis 命令文档：https://redis.io/docs/latest/commands/
RedisBloom 的安装参见 Redis 扩展模块 -- RedisBloom

Cuckoo Filter（布谷鸟过滤器）

Bloom Filter 的增强版，支持删除元素
维基百科对 Cuckoo Filter 的描述
在高 QPS 查询场景下，Cuckoo Filter 通常优于 Bloom Filter。
低误判率 + 高负载率场景，Cuckoo Filter 更省内存。
对应Redis命令： CF.xxx

命令	功能说明	是否创建 Filter	关键参数含义	返回值	示例	使用要点 / 备注
CF.RESERVE	显式创建 Cuckoo Filter	是	`capacity`：容量(必填) `BUCKETSIZE`：每个桶里最多能放多少个 fingerprint（指纹），默认 2(大多数情况下的最优解) `MAXITERATIONS`：重排次数，越大成功率越高 `EXPANSION`：扩容倍数，默认 1（不扩容）	OK	`CF.RESERVE user:cf 100000`	✅ 生产推荐支持删除与计数
CF.ADD	添加一个元素，不去重	是（不存在则创建）	`item`：元素	OK	`CF.ADD user:cf user_1`	若满可能失败
CF.ADDNX	元素不存在时才添加，去重	是（不存在则创建）	`item`	`1` 新增 `0` 已存在	`CF.ADDNX user:cf user_1`	幂等写入首选
CF.INSERT	批量插入	是（不存在则创建）	`ITEMS`：元素列表	OK	`CF.INSERT user:cf ITEMS u1 u2`	默认配置
CF.INSERTNX	批量插入（不存在才加）	是	`ITEMS`	`0/1` 列表	`CF.INSERTNX user:cf ITEMS u1 u2`	幂等 + 批量
CF.EXISTS	判断单个元素是否存在	否	`item`	`1` 可能存在 `0` 不存在	`CF.EXISTS user:cf user_1`	仍有误判
CF.MEXISTS	批量判断是否存在	否	`item...`	`0/1` 列表	`CF.MEXISTS user:cf u1 u9`	高并发推荐
CF.COUNT	返回元素出现次数	否	`item`	整数	`CF.COUNT user:cf user_1`	⭐ Bloom 没有的能力
CF.DEL	删除一个元素	否	`item`	`1` 删除成功 `0` 不存在	`CF.DEL user:cf user_1`	⭐ Bloom 不支持
CF.INFO	查看 Filter 元信息	否	无	KV 列表	`CF.INFO user:cf`	运维分析
CF.SCANDUMP	分块导出 Filter	否	`iterator`	`iterator + data`	`CF.SCANDUMP user:cf 0`	迁移 / 备份
CF.LOADCHUNK	从 dump 恢复 Filter	是	`iterator + data`	OK	`CF.LOADCHUNK user:cf 1 "xxx"`	与 SCANDUMP 配合

Bloom vs Cuckoo

维度	Bloom Filter	Cuckoo Filter
查询复杂度	O(k)（k 个哈希函数）	O(1)（2–4 次 bucket 访问）
插入复杂度	O(k)	平均 O(1)，最坏可能触发重排
删除支持	❌ 原生不支持	✅ 原生支持
误判率（False Positive）	可配置，稳定	可配置，通常更低
漏判（False Negative）	❌ 理论上不会	❌ 理论上不会
空间利用率	高（但受 k 影响）	通常更高（特别是低误判率）
扩容成本	高（需重建）	中等（支持扩展策略）
实现复杂度	低	较高

RedisBloom Cuckoo Filter 不支持设置 误判率，通常容量越大，误判率越低。

CF 命令示例

# 创建 Cuckoo Filter
127.0.0.1:6379> CF.RESERVE user:cf 1000 BUCKETSIZE 2 MAXITERATIONS 500 EXPANSION 2
OK
# 添加元素
127.0.0.1:6379> CF.ADD user:cf user_1
(integer) 1
127.0.0.1:6379> CF.ADD user:cf user_2
(integer) 1
# 可以重复添加元素
127.0.0.1:6379> CF.ADD user:cf user_1
(integer) 1
# 返回元素出现次数
127.0.0.1:6379> CF.COUNT user:cf user_1
(integer) 2
# 判断元素是否存在
127.0.0.1:6379> CF.EXISTS user:cf user_1
(integer) 1
# 批量判断元素是否存在
127.0.0.1:6379> CF.MEXISTS user:cf user_1 user_2 user_100
1) (integer) 1
2) (integer) 1
3) (integer) 0
# 删除元素，一次只删除一个
127.0.0.1:6379> CF.DEL user:cf user_1
(integer) 1
# 因为user_1有两个，所以才是还是能查询出 user_1
127.0.0.1:6379> CF.COUNT user:cf user_1
(integer) 1
# 再次删除
127.0.0.1:6379> CF.DEL user:cf user_1
(integer) 1
# 同名元素已全部删除，查询不到
127.0.0.1:6379> CF.COUNT user:cf user_1
(integer) 0

# 元素不存在时才添加，幂等
127.0.0.1:6379> CF.ADDNX user:cf user_2
(integer) 0
127.0.0.1:6379> CF.ADDNX user:cf user_3
(integer) 1

# 查看 Filter 元信息
127.0.0.1:6379> CF.INFO user:cf
 1) Size                      # 当前 Cuckoo Filter 实际占用的内存大小（字节）
 2) (integer) 1080
 3) Number of buckets         # 当前过滤器中 bucket（桶）的总数量，Size = Number of buckets * Bucket size(默认为2)
 4) (integer) 512
 5) Number of filters         # 内部 子 Cuckoo Filter 的数量
 6) (integer) 1
 7) Number of items inserted  # 成功插入的元素总数（近似）
 8) (integer) 2
 9) Number of items deleted   # 已删除元素的累计次数
10) (integer) 2
11) Bucket size               # 每个 bucket 可容纳的 fingerprint 数，默认为 2
12) (integer) 2
13) Expansion rate            # 过滤器自动扩容倍率，默认为1，0 或 1 表示不扩容（满则失败）
14) (integer) 2
15) Max iterations            # Cuckoo Kick-out 的最大重排次数，值越大，插入成功率越高，但写入延迟可能上升
16) (integer) 500

# 批量添加，key不存在则创建
127.0.0.1:6379> CF.INSERT order:cf CAPACITY 100 ITEMS order1 order2
1) (integer) 1
2) (integer) 1
# 幂等，元素不存在时才添加
127.0.0.1:6379> CF.INSERTNX order:cf CAPACITY 100 ITEMS order1 order2 order100
1) (integer) 0
2) (integer) 0
3) (integer) 1

# 查看类型
127.0.0.1:6379> type order:cf
MBbloomCF

SpringBoot 集成

SpringBoot 的 RedisTemplate 中没有提供对RedisBloom的封装，需要自己封装，我这里封装了一个简易的RedisCuckooFilterTool

package com.example.redisbloom;

/**
 * 基于 RedisBloom 插件的 CuckooFilter 实现
 * https://github.com/RedisBloom/RedisBloom/releases
 * Created by hanqf on 2025/12/22 17:09.
 */

import org.springframework.data.redis.connection.ReturnType;
import org.springframework.data.redis.core.RedisCallback;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;

import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

@Component
public class RedisCuckooFilterTool {

    private final StringRedisTemplate redisTemplate;

    public RedisCuckooFilterTool(StringRedisTemplate redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    /**
     * 初始化 Cuckoo Filter
     * <p>
     * 不能重复执行
     *
     * @param key      Filter 名称
     * @param capacity 预计容量
     */
    public void reserve(String key, long capacity) {
        redisTemplate.execute((RedisCallback<String>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.RESERVE', KEYS[1], " + capacity + ")").getBytes(),
                        ReturnType.STATUS,
                        1,
                        key.getBytes()
                )
        );
    }

    /**
     * 初始化 Cuckoo Filter（高级参数）
     *
     * @param key           Filter 名称
     * @param capacity      预计容量
     * @param bucketSize    每个桶里最多能放多少个 fingerprint（指纹），默认 2(大多数情况下的最优解)
     * @param maxIterations 重排次数，越大成功率越高
     * @param expansion     扩容倍数，默认 1（不扩容）
     */
    public void reserve(String key, long capacity, int bucketSize, int maxIterations, int expansion) {

        String script = String.format(
                "return redis.call('CF.RESERVE', KEYS[1], %d, " +
                        "'BUCKETSIZE', %d, 'MAXITERATIONS', %d, 'EXPANSION', %d)",
                capacity, bucketSize, maxIterations, expansion
        );

        redisTemplate.execute((RedisCallback<String>) connection ->
                connection.scriptingCommands().eval(
                        script.getBytes(),
                        ReturnType.STATUS,
                        1,
                        key.getBytes()
                )
        );
    }

    /**
     * 添加元素（不去重）
     */
    public boolean add(String key, String value) {
        return Boolean.TRUE.equals(redisTemplate.execute((RedisCallback<Boolean>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.ADD', KEYS[1], ARGV[1])").getBytes(),
                        ReturnType.BOOLEAN,
                        1,
                        key.getBytes(),
                        value.getBytes()
                )
        ));
    }

    /**
     * 添加元素（仅当不存在时）
     *
     * @return true 表示成功插入，false 表示已存在
     */
    public boolean addNx(String key, String value) {
        return Boolean.TRUE.equals(redisTemplate.execute((RedisCallback<Boolean>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.ADDNX', KEYS[1], ARGV[1])").getBytes(),
                        ReturnType.BOOLEAN,
                        1,
                        key.getBytes(),
                        value.getBytes()
                )
        ));
    }

    /**
     * 判断元素是否存在
     */
    public boolean exists(String key, String value) {
        return Boolean.TRUE.equals(redisTemplate.execute((RedisCallback<Boolean>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.EXISTS', KEYS[1], ARGV[1])").getBytes(),
                        ReturnType.BOOLEAN,
                        1,
                        key.getBytes(),
                        value.getBytes()
                )
        ));
    }

    /**
     * 批量判断是否存在
     */
    public List<Boolean> mexists(String key, String... items) {
        if (items == null || items.length == 0) {
            return Collections.emptyList();
        }

        byte[][] keysAndArgs = new byte[1 + items.length][];
        keysAndArgs[0] = key.getBytes();
        for (int i = 0; i < items.length; i++) {
            keysAndArgs[i + 1] = items[i].getBytes();
        }

        return redisTemplate.execute((RedisCallback<List<Boolean>>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.MEXISTS', KEYS[1], unpack(ARGV))").getBytes(),
                        ReturnType.MULTI,
                        1,
                        keysAndArgs
                )
        );
    }

    /**
     * 返回元素出现次数（近似）
     */
    public Long count(String key, String value) {
        return redisTemplate.execute((RedisCallback<Long>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.COUNT', KEYS[1], ARGV[1])").getBytes(),
                        ReturnType.INTEGER,
                        1,
                        key.getBytes(),
                        value.getBytes()
                )
        );
    }

    /**
     * 删除元素
     *
     * @return true 删除成功，false 表示不存在
     */
    public boolean delete(String key, String value) {
        return Boolean.TRUE.equals(redisTemplate.execute((RedisCallback<Boolean>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.DEL', KEYS[1], ARGV[1])").getBytes(),
                        ReturnType.BOOLEAN,
                        1,
                        key.getBytes(),
                        value.getBytes()
                )
        ));
    }

    /**
     * 批量插入，不去重
     */
    public List<Boolean> insert(String key, String... items) {
        if (items == null || items.length == 0) {
            return Collections.emptyList();
        }

        byte[][] keysAndArgs = new byte[1 + items.length][];
        keysAndArgs[0] = key.getBytes();
        for (int i = 0; i < items.length; i++) {
            keysAndArgs[i + 1] = items[i].getBytes();
        }

        return redisTemplate.execute((RedisCallback<List<Boolean>>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.INSERT', KEYS[1], 'ITEMS', unpack(ARGV))").getBytes(),
                        ReturnType.MULTI,
                        1,
                        keysAndArgs
                )
        );
    }

    /**
     * 批量插入，去重
     */
    public List<Boolean> insertNx(String key, String... items) {
        if (items == null || items.length == 0) {
            return Collections.emptyList();
        }

        byte[][] keysAndArgs = new byte[1 + items.length][];
        keysAndArgs[0] = key.getBytes();
        for (int i = 0; i < items.length; i++) {
            keysAndArgs[i + 1] = items[i].getBytes();
        }

        return redisTemplate.execute((RedisCallback<List<Boolean>>) connection ->
                connection.scriptingCommands().eval(
                        ("return redis.call('CF.INSERTNX', KEYS[1], 'ITEMS', unpack(ARGV))").getBytes(),
                        ReturnType.MULTI,
                        1,
                        keysAndArgs
                )
        );
    }

    /**
     * 获取 Cuckoo Filter 元信息
     */
    public Map<String, Object> info(String key) {
        List<Object> result = redisTemplate.execute(
                (RedisCallback<List<Object>>) connection ->
                        connection.scriptingCommands().eval(
                                "return redis.call('CF.INFO', KEYS[1])".getBytes(),
                                ReturnType.MULTI,
                                1,
                                key.getBytes()
                        )
        );

        if (result == null || result.isEmpty()) {
            return Collections.emptyMap();
        }

        Map<String, Object> infoMap = new LinkedHashMap<>();
        for (int i = 0; i < result.size(); i += 2) {
            String field = toString(result.get(i));
            Object value = result.get(i + 1);
            infoMap.put(field, value);
        }

        return infoMap;
    }

    /**
     * 字节数组转字符串
     * info 返回的 List
     * [
     *   byte[]("Size"),                  Long(1080),
     *   byte[]("Number of buckets"),     Long(512),
     *   byte[]("Number of filters"),     Long(1),
     *   ...
     * ]
     */
    private String toString(Object obj) {
        if (obj instanceof byte[]) {
            return new String((byte[]) obj);
        }
        return String.valueOf(obj);
    }
}