ZRANGEBYSCORE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ ZRANGEBYSCORE ✨

okay bestie, welcome to the ZRANGEBYSCORE(3valkey) page of the Valkey Command Manual 💖 this one's a whole vibe, let's get into it.

🌸 NAME 🌸

zrangebyscore — returns members in a sorted set within a range of scores. that's it, that's the girl 💅

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

so basically: this returns all the elements in the sorted set at key whose score is between min and max — and yes, that range is inclusive, so elements with a score exactly equal to min or max are invited to the party too. the elements come back ordered from low to high scores. no cap.

and the elements that share the same score? they come back in lexicographical order. and the way that's literally free — it falls right out of how sorted sets are implemented in Valkey, no extra computation required. iconic behavior, honestly.

the optional LIMIT argument lets you grab only a slice of the matching elements (kinda like SELECT LIMIT offset, count in SQL, iykyk). a negative count returns all the elements starting from the offset. but bestie, listen: if offset is large, the sorted set has to be traversed through offset elements before it even gets to the ones you want to return, and that can add up to O(N) time complexity. so like, don't be weird with it.

the optional WITHSCORES argument makes the command return both the element and its score, instead of just the element alone. the more you know 💫

💜 Exclusive intervals and infinity 💜

min and max can be -inf and +inf, which means you don't have to know the highest or lowest score in the sorted set just to get everything from or up to a certain score. so freeing, honestly.

by default the interval specified by min and max is closed (inclusive). but you can specify an open (exclusive) interval 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 (so 5 and 10 are excluded — sorry babes, not this time).

🧚 Alternative 🧚

ZRANGE with the BYSCORE argument. same energy, different font 💅

🫶 REPLY 🫶

  • valkey-protocol(7) Array reply: a list of the members with, optionally, their scores in the specified score range. it's giving structured data ✨

🔥 COMPLEXITY 🔥

O(log(N)+M) where N is the number of elements in the sorted set and M is the number of elements being returned. but if M is constant (like, say you're always asking for the first 10 elements with LIMIT), you can just consider it O(log(N)). slay, we love a bounded girlie.

👑 ACL CATEGORIES 👑

@read @slow @sortedset

🌈 HISTORY 🌈

  • Available since: 1.0.5
  • Changed in 2.0.0: added the WITHSCORES modifier. glow-up era ✨

🍓 EXAMPLES 🍓

127.0.0.1:6379> ZADD myzset 1 "one"
(integer) 1
127.0.0.1:6379> ZADD myzset 2 "two"
(integer) 1
127.0.0.1:6379> ZADD myzset 3 "three"
(integer) 1
127.0.0.1:6379> ZRANGEBYSCORE myzset -inf +inf
1) "one"
2) "two"
3) "three"
127.0.0.1:6379> ZRANGEBYSCORE myzset 1 2
1) "one"
2) "two"
127.0.0.1:6379> ZRANGEBYSCORE myzset (1 2
1) "two"
127.0.0.1:6379> ZRANGEBYSCORE myzset (1 (2
(empty array)

💫 Pattern: weighted random selection of an element 💫

normally ZRANGEBYSCORE is just used to get a range of items where the score is the indexed integer key — but bestie, you can do some less obvious things with this command. and that's the fun part.

for example, a common problem when implementing Markov chains and other algorithms is selecting an element at random from a set, but different elements may have different weights that change how likely they are to be picked. main character energy for the heavy ones, ig.

this is how we use this command in order to mount such an algorithm:

imagine you have elements A, B and C with weights 1, 2 and 3. you compute the sum of the weights, which is 1+2+3 = 6.

at this point you add all the elements into a sorted set using this algorithm:

SUM = ELEMENTS.TOTAL_WEIGHT // 6 in this case.
SCORE = 0
FOREACH ELE in ELEMENTS
    SCORE += ELE.weight / SUM
    ZADD KEY SCORE ELE
END

this means that you set:

A to score 0.16
B to score .5
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...). yeah. do your homework 😭

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

obsessed. periodt.

💖 SEE ALSO 💖

bzmpop(3valkey), bzpopmax(3valkey), bzpopmin(3valkey), zadd(3valkey), zcard(3valkey), zcount(3valkey), zdiff(3valkey), zdiffstore(3valkey), zincrby(3valkey), zinter(3valkey), zintercard(3valkey), zinterstore(3valkey), zlexcount(3valkey), zmpop(3valkey), zmscore(3valkey), zpopmax(3valkey), zpopmin(3valkey), zrandmember(3valkey), zrange(3valkey), zrangebylex(3valkey), zrangestore(3valkey), zrank(3valkey), zrem(3valkey), zremrangebylex(3valkey), zremrangebyrank(3valkey), zremrangebyscore(3valkey), zrevrange(3valkey), zrevrangebylex(3valkey), zrevrangebyscore(3valkey), zrevrank(3valkey), zscan(3valkey), zscore(3valkey), zunion(3valkey), zunionstore(3valkey)

and that's the page!! this one's from version 9.0.0, dated 2025-10-21 — go forth and range those scores bestie, ily 🫶💖✨

📦 where this page comes from