HRANDFIELD(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 HRANDFIELD — the Valkey command manual page 💖

okay bestie, buckle up, we're doing HRANDFIELD(3valkey) from the Valkey Command Manual and it's literally the most chaotic-fun hash command in the whole building 🎲✨

✨ NAME ✨

hrandfield — pulls one or more random fields out of a hash. it's giving mystery box 🎁

🌸 SYNOPSIS 🌸

HRANDFIELD key [count [WITHVALUES]]

🦋 DESCRIPTION 🦋

okay so. if you call it with just the key and nothing else, you get back one single random field from the hash sitting at that key. one field. random. no cap. 🎀

now if the count you pass is positive, you get an array of distinct fields back. how long is that array? it's either count or the hash's number of fields (valkey-hlen(7) HLEN) — whichever one is lower. so you can't over-ask, bestie, the hash will simply not let you 💅

but if you call it with a negative count?? whole different vibe. the behavior changes and the command is allowed to return the same field multiple times 🙈 in that case, the number of fields you get back is the absolute value of the count you specified. yes, absolute value. math is math.

and the optional WITHVALUES modifier? it changes the reply so it also includes the respective values of the randomly selected hash fields. iconic. you get the whole pairing 🌈

💜 REPLY 💜

RESP2

any of the following, king:

  • valkey-protocol(7) Nil reply: if the key doesn't exist 😭
  • valkey-protocol(7) Bulk string reply: a single, randomly selected field when the count option is not used
  • valkey-protocol(7) Array reply: a list containing count fields when the count option is used, or an empty array if the key does not exists.
  • valkey-protocol(7) Array reply: a list of fields and their values when count and WITHVALUES were both used.

RESP3

any of the following:

  • valkey-protocol(7) Null reply: if the key doesn't exist
  • valkey-protocol(7) Bulk string reply: a single, randomly selected field when the count option is not used
  • valkey-protocol(7) Array reply: a list containing count fields when the count option is used, or an empty array if the key does not exists.
  • valkey-protocol(7) Array reply: a list of fields and their values when count and WITHVALUES were both used.

(yeah the two lists are basically twins, only the not-found case differs — RESP2 says Nil, RESP3 says Null. slay 💅)

⚡ COMPLEXITY ⚡

O(N) where N is the number of fields returned. so like, the more you ask for, the more work it does. obviously. 🍓

👑 ACL CATEGORIES 👑

@hash @read @slow

📜 HISTORY 📜

  • Available since: 6.2.0

🌟 EXAMPLES 🌟

127.0.0.1:6379> HSET coin heads obverse tails reverse edge null
(integer) 3
127.0.0.1:6379> HRANDFIELD coin
"heads"
127.0.0.1:6379> HRANDFIELD coin
"heads"
127.0.0.1:6379> HRANDFIELD coin -5 WITHVALUES
 1) "heads"
 2) "obverse"
 3) "tails"
 4) "reverse"
 5) "edge"
 6) "null"
 7) "heads"
 8) "obverse"
 9) "edge"
10) "null"

(notice how heads showed up twice in that last one? that's the negative-count chaos in action, we love her 🫶)

Specification of the behavior when count is passed

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

  • No repeated fields are returned.
  • If count is bigger than the number of fields in the hash, the command will only return the whole hash without additional fields.
  • The order of fields in the reply is not truly random, so it is up to the client to shuffle them if needed.

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

  • Repeating fields are possible.
  • Exactly count fields, or an empty array if the hash is empty (non-existing key), are always returned.
  • The order of fields in the reply is truly random.
real talk bestie: positive count = unique fields but the order is fake-random. negative count = repeats allowed but the order is the real deal. pick your fighter 🔥

🧚 SEE ALSO 🧚

hdel(3valkey), hexists(3valkey), hexpire(3valkey), hexpireat(3valkey), hexpiretime(3valkey), hget(3valkey), hgetall(3valkey), hgetex(3valkey), hincrby(3valkey), hincrbyfloat(3valkey), hkeys(3valkey), hlen(3valkey), hmget(3valkey), hmset(3valkey), hpersist(3valkey), hpexpire(3valkey), hpexpireat(3valkey), hpexpiretime(3valkey), hpttl(3valkey), hscan(3valkey), hset(3valkey), hsetex(3valkey), hsetnx(3valkey), hstrlen(3valkey), httl(3valkey), hvals(3valkey)

and that's the whole page!! this one's from Valkey 9.0.0, dated 2025-10-21, and it goes out to HRANDFIELD(3valkey) — go forth and randomize, bestie 💖✨🎀

📦 where this page comes from