Leaderboards and ranking pages
Fetch a page of leaderboard entries by rank, optionally including their scores.
Redis · Command
ZRANGE
Returns members from a sorted set selected by rank, score, or lexicographical range. Optional reverse ordering, pagination, and score output support ranking, filtering, and windowed reads.
- Since
- 6.2.0
How it works
ZRANGE reads members from a sorted set using an index range by default. BYSCORE changes the bounds to scores, BYLEX changes them to lexicographical member values, REV reverses the result order, LIMIT paginates matches, and WITHSCORES includes each member's score.
Syntax
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]Parameters
| Name | Type | Description |
|---|---|---|
key | key | Name of the sorted-set key. |
start | string or number | Starting rank, score bound, or lexicographical bound, depending on the selected mode. |
stop | string or number | Ending rank, score bound, or lexicographical bound, depending on the selected mode. |
BYSCORE | BYLEX | option | Select score-based or lexicographical bounds. |
REV | option | Reverse the result order and interpretation of the range. |
LIMIT offset count | option | Skip offset matches and return up to count matches. |
WITHSCORES | option | Include scores alongside members. |
Returns
An array of matching sorted-set members; with WITHSCORES, each member is accompanied by its score. A non-overlapping range returns an empty array.
Key points
- The command reads members from the sorted set stored at the specified key.
- One command supports rank-based, score-based, and lexicographical range selection.
- Negative rank indexes address members relative to the set's end.
- An oversized ending rank is clamped to the last available member.
Common mistakes
- The start and stop bounds are inclusive. Use a parenthesis on score or lexicographical bounds when an exclusive boundary is required.
- Invalid or non-overlapping index ranges return an empty list rather than an error.
Example: Rank and score range queries
ZADD leaderboard 120 alice 95 bob 110 carol
ZRANGE leaderboard 0 -1 WITHSCORES
ZRANGE leaderboard 100 120 BYSCORE REV LIMIT 0 2Adds three members, lists them by rank with scores, then retrieves up to two members whose scores fall in the selected range in descending score order.
When to use it
Score-range filtering
Select records whose sorted-set scores fall between two bounds.
Lexicographical indexing
Use equal-score members and BYLEX bounds to retrieve a name or identifier interval.
Interview questions
QHow does default ZRANGE indexing work?
By default, ZRANGE interprets start and stop as zero-based rank indexes, and both bounds are inclusive. Negative indexes count backward from the end, with -1 representing the final member.
Follow-up: How can it retrieve the highest-scoring members? Use REV together with BYSCORE, then apply LIMIT, for example: ZRANGE key +inf -inf BYSCORE REV LIMIT 0 10.
QHow does a score-based query differ from the default query?
BYSCORE makes the two bounds score limits instead of indexes. Score bounds can be inclusive or exclusive, and special values such as -inf and +inf can represent unbounded ends.
Follow-up: How would you return scores as well? Add WITHSCORES; the response alternates each returned member with its score.
QWhat options control ordering, pagination, and returned data?
ZRANGE supports BYLEX for member-name ranges, REV for reverse ordering, LIMIT offset count for pagination, and WITHSCORES for returning scores. Its complexity is O(log(N)+M), where M is the number of returned elements.
Follow-up: Why should a caller avoid unrestricted large reads? Because M grows with the result size, so limiting the requested range reduces work and response size.
Related
ZADDZCOUNTZRANKZREVRANGEZRANGESTOREZLEXCOUNT