Using Redis SCAN to Safely Enumerate Keys Instead of KEYS

When you need to inspect Redis keys with a specific prefix, using keys user_token* on a production system with millions of keys can block the single‑threaded server because the KEYS command performs a full O(n) scan.

Incident

Developers ran keys user_token* to count logged‑in users, which caused Redis to become unresponsive.

Root Cause Analysis

Redis executes commands sequentially; the KEYS command traverses the entire keyspace, so with a large number of keys it consumes significant time and blocks other operations.

Solution

Use the SCAN command, which iterates the keyspace incrementally using a cursor, avoiding thread blockage. It supports MATCH for pattern filtering and COUNT to hint the number of keys returned per iteration, though results may contain duplicates and require client‑side deduplication.

Complexity remains O(n) but is performed in small steps. COUNT controls how many slots are examined per call, not the result size. Pattern matching works like KEYS. The server does not keep cursor state; the client does. Duplicates may appear and must be filtered. An empty result does not mean completion; the cursor must be zero.

SCAN Command Syntax

SCAN cursor [MATCH pattern] [COUNT count]

Explanation: cursor is the iteration position, MATCH filters keys, and COUNT suggests how many elements to return per call.

Example

redis> scan 0 match user_token* count 5
1) "6"
2) "user_token:1000"
3) "user_token:1001"
4) "user_token:1010"
5) "user_token:2300"

Starting from cursor 0 returns a new cursor (6) and a batch of matching keys. Continue scanning with the new cursor:

redis> scan 6 match user_token* count 5
1) "10"
2) "user_token:3100"
3) "user_token:1201"
4) "user_token:1410"
5) "user_token:5300"

Conclusion

SCANNING keys is a common interview topic and a practical technique for large Redis deployments; using it correctly prevents performance degradation that occurs with KEYS on massive datasets.