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.

ZSCAN

Last updated 
ZSCAN key cursor [MATCH pattern] [COUNT count] [NOSCORES]
Group
Sorted 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

ZSCAN walks the sorted set at key a few members at a time, returning each member with its score (or the members alone with NOSCORES). 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 sorted 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. The order of members is not guaranteed; use ZRANGE for ordered access.

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.
NOSCORES Return only the members, without their scores.

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 a flat array of member, score, member, score, … (scores as bulk strings). With NOSCORES, the flat array holds the members only. 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 sorted 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.

Examples

Section titled “Examples”
127.0.0.1:6379> ZADD board 10 "alice" 20 "bob" 30 "anna"
(integer) 3
127.0.0.1:6379> ZSCAN board 0 MATCH "a*"
1) "0"
2) 1) "alice"
   2) "10"
   3) "anna"
   4) "30"
127.0.0.1:6379> ZSCAN board 0 NOSCORES
1) "0"
2) 1) "alice"
   2) "bob"
   3) "anna"

Compatibility

Section titled “Compatibility”

Same as Redis 8.0 and Valkey 8. NOSCORES is accepted by ZSCAN only: SCAN, SSCAN and HSCAN answer ERR NOSCORES option can only be used in ZSCAN.

See also

Section titled “See also”

ZRANGE, SCAN, SSCAN, HSCAN