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.

ZRANGE

Last updated 
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]
Group
Sorted set
Complexity
O(log(N)+M) where N is the size of the sorted set and M is the number of members returned
Arity
-4 (at least 4 words, counting the command name)
Flags
read-only
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

ZRANGE returns members of the sorted set at key in a range. What start and stop mean depends on the options:

  • By rank (default): start and stop are zero-based positions, both included. Negative values count from the end, so ZRANGE key 0 -1 returns everything. Out-of-range positions are clamped.
  • BYSCORE: start and stop are scores. They are inclusive unless prefixed with (, and -inf / +inf are allowed.
  • BYLEX: start and stop are lexicographic bounds: [value (inclusive), (value (exclusive), - or +. Use this when all members share the same score.

Members come back from the lowest score to the highest (ties in lexicographic order). REV reverses the order; with BYSCORE or BYLEX and REV, give the higher bound first.

Options

Section titled “Options”
Option Effect
BYSCORE Treat start and stop as scores.
BYLEX Treat start and stop as lexicographic bounds.
REV Return members from the highest to the lowest.
LIMIT offset count Skip offset matching members, then return at most count. A negative count returns all remaining members; a negative offset returns nothing. Only with BYSCORE or BYLEX.
WITHSCORES Return each member with its score. Not allowed with BYLEX.

BYSCORE and BYLEX cannot be combined, and BYSCORE, BYLEX and REV can each be given once. Options are checked before the range and the key.

Return value

Section titled “Return value”
Case RESP2 RESP3
Success Array of members Same
With WITHSCORES Flat array: member, score, member, score, … (scores as bulk strings) Array of two-element arrays: [member, score], the score a double
Key does not exist or empty range Empty array Same

Errors:

  • ERR syntax error for an unknown, repeated or conflicting option.
  • ERR syntax error, LIMIT is only supported in combination with either BYSCORE or BYLEX.
  • ERR syntax error, WITHSCORES not supported in combination with BYLEX.
  • ERR value is not an integer or out of range for a non-integer rank or LIMIT value.
  • ERR min or max is not a float for a bad score bound.
  • ERR min or max not valid string range item for a bad lexicographic bound.
  • WRONGTYPE if key holds a value that is not a sorted set.

Examples

Section titled “Examples”
127.0.0.1:6379> ZADD board 1 "a" 2 "b" 3 "c" 4 "d"
(integer) 4
127.0.0.1:6379> ZRANGE board 0 1 WITHSCORES
1) "a"
2) "1"
3) "b"
4) "2"
127.0.0.1:6379> ZRANGE board (1 +inf BYSCORE LIMIT 0 2
1) "b"
2) "c"
127.0.0.1:6379> ZRANGE board +inf 3 BYSCORE REV
1) "d"
2) "c"
127.0.0.1:6379> ZRANGE board 0 -1 REV
1) "d"
2) "c"
3) "b"
4) "a"

Compatibility

Section titled “Compatibility”

Same as Redis 7.4 and Valkey 8.

See also

Section titled “See also”

ZRANGESTORE, ZRANGEBYSCORE, ZRANGEBYLEX, ZREVRANGE, ZRANK