SCAN

SCAN walks the keyspace a little at a time. Start with cursor 0, then pass the cursor each reply returns into the next call, until a reply’s cursor is 0 again. Each call returns a page of key names. Unlike KEYS, no single call has to look at the whole database.

A full iteration returns every key that existed for the whole iteration exactly once, however the keyspace changes in the meantime. Keys added or removed during the iteration may or may not appear.

Options

Option	Effect
MATCH pattern	Return only keys matching this glob pattern (same syntax as KEYS). The filter is applied after the page is read, so a page can be empty while the cursor is not 0.
COUNT count	A hint for how much work to do per call. Default 10; must be at least 1.
TYPE type	Return only keys of this type, using the names TYPE replies (string, list, set, zset, hash, stream, …), compared without case. A name that is no type returns an empty, finished scan.

Return value

Case	RESP2	RESP3
Always	Array of two elements: the next cursor as a bulk string, then an array of key names	Same

Errors:

• ERR invalid cursor when the cursor is not an unsigned integer.
• ERR value is not an integer or out of range when COUNT is not an integer.
• ERR syntax error for COUNT below 1, an option without its value, or an unknown option.
• ERR NOSCORES option can only be used in ZSCAN if you pass NOSCORES.

Examples

127.0.0.1:6379> MSET user:1 "ada" user:2 "grace" order:1 "book"
OK
127.0.0.1:6379> SCAN 0 MATCH user:* COUNT 100
1) "0"
2) 1) "user:1"
   2) "user:2"
127.0.0.1:6379> SCAN 0 TYPE list
1) "0"
2) (empty array)

Compatibility

Same options, reply shape and errors as Redis 7 and Valkey 8. Redis and Valkey may return a key more than once during an iteration; HotKV does not, but code that tolerates duplicates works unchanged.

See also

KEYS, TYPE, SSCAN, HSCAN, ZSCAN