ZRANGEBYSCORE key min max [WITHSCORES ] [LIMIT offset count]

Returns all the elements in the sorted set at key with a score between min and max (including elements with score equal to min or max). The elements are considered to be ordered from low to high scores.

The elements having the same score are returned in lexicographical order (this follows from a property of the sorted set implementation in Redis and does not involve further computation).

The optional LIMIT argument can be used to only get a range of the matching elements (similar to SELECT LIMIT offset, count in SQL). A negative count returns all elements from the offset. Keep in mind that if offset is large, the sorted set needs to be traversed for offset elements before getting to the elements to return, which can add up to O(N) time complexity.

The optional WITHSCORES argument makes the command return both the element and its score, instead of the element alone. This option is available since Redis 2.0.

Exclusive intervals and infinity

min and max can be -inf and +inf, so that you are not required to know the highest or lowest score in the sorted set to get all elements from or up to a certain score.

By default, the interval specified by min and max is closed (inclusive). It is possible to specify an open interval (exclusive) by prefixing the score with the character (. For example:

ZRANGEBYSCORE zset (1 5

Will return all elements with 1 < score <= 5 while:

ZRANGEBYSCORE zset (5 (10

Will return all the elements with 5 < score < 10 (5 and 10 excluded).

@return

@array-reply: list of elements in the specified score range (optionally with their scores).

@examples

redis> ZADD myzset 1 "one"
TBD
redis> ZADD myzset 2 "two"
TBD
redis> ZADD myzset 3 "three"
TBD
redis> ZRANGEBYSCORE myzset -inf +inf
TBD
redis> ZRANGEBYSCORE myzset 1 2
TBD
redis> ZRANGEBYSCORE myzset (1 2
TBD
redis> ZRANGEBYSCORE myzset (1 (2
TBD
redis> ```
TBD
redis> ## Pattern: weighted random selection of an element
TBD
redis> Normally [`ZRANGEBYSCORE`](/commands/zrangebyscore) is simply used in order to get range of items
TBD
redis> where the score is the indexed integer key, however it is possible to do less
TBD
redis> obvious things with the command.
TBD
redis> For example a common problem when implementing Markov chains and other algorithms
TBD
redis> is to select an element at random from a set, but different elements may have
TBD
redis> different weights that change how likely it is they are picked.
TBD
redis> This is how we use this command in order to mount such an algorithm:
TBD
redis> Imagine you have elements A, B and C with weights 1, 2 and 3.
TBD
redis> You compute the sum of the weights, which is 1+2+3 = 6
TBD
redis> At this point you add all the elements into a sorted set using this algorithm:
TBD
redis> ```
TBD
redis> SUM = ELEMENTS.TOTAL_WEIGHT // 6 in this case.
TBD
redis> SCORE = 0
TBD
redis> FOREACH ELE in ELEMENTS
TBD
redis> SCORE += ELE.weight / SUM
TBD
redis> ZADD KEY SCORE ELE
TBD
redis> END
TBD
redis> ```
TBD
redis> This means that you set:
TBD
redis> ```
TBD
redis> A to score 0.16
TBD
redis> B to score .5
TBD
redis> C to score 1

Since this involves approximations, in order to avoid C is set to, like, 0.998 instead of 1, we just modify the above algorithm to make sure the last score is 1 (left as an exercise for the reader…).

At this point, each time you want to get a weighted random element, just compute a random number between 0 and 1 (which is like calling rand() in most languages), so you can just do:

RANDOM_ELE = ZRANGEBYSCORE key RAND() +inf LIMIT 0 1

History

• Starting with Redis version 2.0.0: Added the WITHSCORES modifier.