ZRANDMEMBER(3valkey)

💖 ZRANDMEMBER — the valkey command manual, but make it cute 💖

okay so bestie, welcome to ZRANDMEMBER from the Valkey Command Manual — yeah, it's ZRANDMEMBER(3valkey), and no, it's not scary, it's literally just a sorted set picking a random member for you like a little raffle 🎀

---

✨ NAME ✨

zrandmember — returns one or more random members from a sorted set. it's giving lucky draw energy, fr fr 🌸

---

🌈 SYNOPSIS 🌈

ZRANDMEMBER key [count [WITHSCORES]]

that's it. that's the whole vibe. 🦋

---

👑 DESCRIPTION 👑

okay so when you call it with just the key argument, it returns a random element from the sorted set value stored at key. one element. randomly. slay.

if the count argument you pass is positive, you get back an array of distinct elements — no duplicates, we don't do that here 💅. and the array's length is either count or the sorted set's cardinality (ZCARD), whichever is lower. so if you ask for 100 and there's only 6 members, you get 6. no cap.

if you call it with a negative count, everything changes bestie — the command is allowed to return the same element multiple times. the number of returned elements is the absolute value of the specified count. so -5 means 5 elements, repeats welcome 🙈.

and the optional WITHSCORES modifier changes the reply so it also includes the respective scores of the randomly selected elements from the sorted set. scores AND members, iconic. ✨

---

🫶 REPLY 🫶

💜 RESP2

• valkey-protocol(7) Bulk string reply: without the additional count argument, the command returns a randomly selected member, or a valkey-protocol(7) Nil reply when key doesn't exist.
• valkey-protocol(7) Array reply: when the additional count argument is passed, the command returns an array of members, or an empty array when key doesn't exist. if the WITHSCORES modifier is used, the reply is a list of members and their scores from the sorted set.

💙 RESP3

• valkey-protocol(7) Bulk string reply: without the additional count argument, the command returns a randomly selected member, or a valkey-protocol(7) Null reply when key doesn't exist.
• valkey-protocol(7) Array reply: when the additional count argument is passed, the command returns an array of members, or an empty array when key doesn't exist. if the WITHSCORES modifier is used, the reply is a list of members and their scores from the sorted set.

yes, RESP2 says Nil and RESP3 says Null. different protocols, different words, same energy. don't come for me, that's literally what it says 😭

---

⚡ COMPLEXITY ⚡

O(N) where N is the number of members returned. so the more you ask for, the more work it does. math is math, bestie 📐

---

🔐 ACL CATEGORIES 🔐

• @read
• @slow
• @sortedset

three little tags, all of them matter 🎀

---

🕰️ HISTORY 🕰️

• Available since: 6.2.0

she's not new new, but she's not ancient either. millennial-coded. 💅

---

🍓 EXAMPLES 🍓

127.0.0.1:6379> ZADD dadi 1 uno 2 due 3 tre 4 quattro 5 cinque 6 sei
(integer) 6
127.0.0.1:6379> ZRANDMEMBER dadi
"uno"
127.0.0.1:6379> ZRANDMEMBER dadi
"uno"
127.0.0.1:6379> ZRANDMEMBER dadi -5 WITHSCORES
 1) "cinque"
 2) "5"
 3) "sei"
 4) "6"
 5) "quattro"
 6) "4"
 7) "quattro"
 8) "4"
 9) "sei"
10) "6"

see how it pulled "uno" twice in a row? that's the ✨randomness✨. and with -5 WITHSCORES you can literally see "quattro" and "sei" showing up twice — that's the negative count doing its repeat thing, and the scores riding along for the trip 🔥

---

🧚 Specification of the behavior when count is passed

when the count argument is a positive value, this command behaves as follows:

• No repeated elements are returned. 🙅
• If count is bigger than the cardinality of the sorted set, the command will only return the whole sorted set without additional elements. (you can't get blood from a stone, bestie)
• The order of elements in the reply is not truly random, so it is up to the client to shuffle them if needed. 👈 this one matters, don't forget it

when the count is a negative value, the behavior changes as follows:

• Repeating elements are possible. 🔁
• Exactly count elements, or an empty array if the sorted set is empty (non-existing key), are always returned.
• The order of elements in the reply is truly random. 🌈

---

👀 SEE ALSO 👀

the whole sorted set friend group, go say hi:

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), zrange(3valkey), zrangebylex(3valkey), zrangebyscore(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)

---

okay that's the whole page!! 🥳 this was ZRANDMEMBER(3valkey), from Valkey 9.0.0, dated 2025-10-21. love that for us. go pick something random, bestie — you've earned it 💖✨🎀