Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

SSCAN

Last updated 
SSCAN key cursor [MATCH pattern] [COUNT count]
Group
Set
Complexity
O(1) for every call, O(N) for a full iteration
Arity
-3 (at least 3 words, counting the command name)
Flags
read-only
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

SSCAN walks the set at key a few members at a time. Start with cursor 0; each reply gives you the next cursor to pass in. The iteration is complete when the server returns cursor 0 again.

Members that stay in the set for the whole iteration are returned at least once. A member can be returned more than once, and members added or removed during the iteration may or may not be returned.

Options

Section titled “Options”
Option Effect
MATCH pattern Return only members that match the glob-style pattern. Filtering happens after members are fetched, so a call can return nothing and still have a non-zero cursor.
COUNT count A hint for how much work to do per call. Default 10. Must be at least 1.

The cursor is checked first, then the key’s type, then the options; when the key does not exist, the options are not checked and the reply is an empty page.

Return value

Section titled “Return value”
Case RESP2 RESP3
Success Two-element array: the next cursor as a bulk string, then an array of members Same
Key does not exist ["0", []] Same

Errors:

  • ERR invalid cursor if cursor is not an unsigned integer.
  • WRONGTYPE if key holds a value that is not a set.
  • ERR value is not an integer or out of range if the COUNT value is not an integer, and ERR syntax error if it is below 1, an option is unknown, or an option is missing its value.
  • ERR NOVALUES option can only be used in HSCAN if you pass NOVALUES.
  • ERR NOSCORES option can only be used in ZSCAN if you pass NOSCORES.

Examples

Section titled “Examples”
127.0.0.1:6379> SADD tags "redis" "cache" "rust"
(integer) 3
127.0.0.1:6379> SSCAN tags 0 MATCH "r*"
1) "0"
2) 1) "redis"
   2) "rust"

Compatibility

Section titled “Compatibility”

Same as Redis 7.4 and Valkey 8.

See also

Section titled “See also”

SMEMBERS, SCAN, HSCAN, ZSCAN