Redis SCAN 命令使用指南

SCAN 命令是 Redis 中用于增量式迭代键空间(key space)的重要命令，特别适合处理大型数据库而不会像 KEYS 命令那样阻塞服务器。

基本用法

语法

SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]

参数说明

• cursor: 游标值，第一次迭代时为 0，后续使用服务器返回的新游标
• MATCH pattern: 可选，匹配键的模式(glob风格)
• COUNT count: 可选，建议每次迭代返回的元素数量(默认10)
• TYPE type: Redis 6.0+ 可选，指定返回的键类型(string, list, set, zset, hash, stream)

使用示例

基本迭代

> SCAN 0
1) "17"            # 下一次迭代使用的游标
2) 1) "key:1"      # 返回的键列表
   2) "key:2"
   3) "key:3"

带模式匹配

> SCAN 0 MATCH user:*
1) "23"
2) 1) "user:1001"
   2) "user:1002"

指定返回数量

> SCAN 0 COUNT 50
1) "38"
2) 1) "key:1"
   2) "key:2"
   ...(最多约50个键)

指定键类型(Redis 6.0+)

> SCAN 0 TYPE hash
1) "42"
2) 1) "user:profile:1001"
   2) "product:details:5001"

完整迭代流程

cursor = '0'
keys = []
while cursor != 0:
    cursor, partial_keys = redis.scan(cursor=cursor, match="prefix:*", count=100)
    keys.extend(partial_keys)

注意事项

1. 非阻塞性: SCAN 不会像 KEYS 那样长时间阻塞服务器
2. 不保证完整性: 迭代期间如果数据库修改，可能会看到重复或遗漏的键
3. COUNT是建议值: 实际返回数量可能多于或少于COUNT指定值
4. 游标0表示结束: 当返回游标为0时表示迭代完成
5. 一致性: 单个SCAN命令调用期间保证一致性

相关命令

• SSCAN: 迭代集合键中的元素
• HSCAN: 迭代哈希键中的字段
• ZSCAN: 迭代有序集合中的元素

SCAN命令是处理大型Redis数据库时遍历键的安全方式，建议在生产环境中替代KEYS命令使用。