Using Redis SCAN to Safely Enumerate Keys Instead of KEYS

Introduction: When needing to view Redis key usage, especially keys with certain prefixes, a naive approach can cause problems.

Incident: The team stored user tokens with keys like user_token:userid and used the KEYS command to count logged‑in users, which blocked Redis and caused a near‑outage because KEYS scans the entire keyspace with O(n) complexity on a single‑threaded server.

Analysis: With millions of keys, KEYS blocks the server; Redis processes commands sequentially, so other operations wait.

Solution: Use the SCAN command, which iterates the keyspace incrementally using a cursor, providing non‑blocking traversal, optional MATCH pattern, and COUNT hint. SCAN still has O(n) overall complexity but spreads work across calls.

Features of SCAN :

1. Complexity is O(n) but performed step‑by‑step, avoiding thread blockage. 2. Supports a COUNT parameter that hints how many slots to examine per iteration. 3. Provides pattern matching similar to KEYS . 4. The server does not keep state; the cursor returned to the client represents the iteration state. 5. Results may contain duplicates, so the client must deduplicate. 6. An empty result does not mean the scan is finished; the cursor must be zero to end.

Command format: SCAN cursor [MATCH pattern] [COUNT count]

Example usage:

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"

Continue scanning from the returned cursor until it returns 0:

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: SCAN is a common interview topic and a safe way to enumerate large keysets in production; using it correctly avoids performance degradation and keeps Redis responsive.