The Redis HRANDFIELD
command allows us to get a random field from a given key.
The command accepts several arguments that allows us to specify the number of random fields returned, whether to include the same field multiple times, and whether or not to include the values with each field returned.
The HRANDFIELD
command was introduced in Redis 6.2.0.
Syntax
The syntax goes like this:
HRANDFIELD key [count [WITHVALUES]]
Example
Suppose we create the following hash:
HSET pet name "Wag" color "Brown" age 37 weight 10 height 59
Result:
(integer) 5
This integer reply tells us that five fields were added to the hash.
We can now use the HRANDFIELD
command to return a random field from that hash:
HRANDFIELD pet
Result:
"age"
Let’s run it again:
HRANDFIELD pet
Result:
"height"
Return Multiple Fields
We can return more than one random field with the HRANDFIELD
command. To do this, we need to pass an optional count
argument to specify how many fields to return:
HRANDFIELD pet 3
Result:
1) "height" 2) "age" 3) "name"
Here it is again with a different count
argument:
HRANDFIELD pet 4
Result:
1) "color" 2) "age" 3) "name" 4) "weight"
When passing a positive count
value, only distinct fields are returned, and the result is not truly random. When passing a negative value, duplicate fields can be returned (i.e. the same field can be returned multiple times), and the result is truly random. See below for examples of passing a negative value.
Allow Non-Distinct Fields
By default, only distinct fields are returned, but we can use a negative count value to specify that non-distinct fields can be returned.
Here’s an example:
HRANDFIELD pet -4
Result:
1) "height" 2) "height" 3) "name" 4) "height"
In this case, the height
field is returned three times. This wouldn’t have happened if we had used a positive count
value.
But this doesn’t mean that there will always be duplicate field names returned. Here’s what happens when I run the command again:
HRANDFIELD pet -4
Result:
1) "name" 2) "weight" 3) "color" 4) "age"
However, we can use a value that’s larger than the number of fields in the hash to return an array of values that’s greater than the number of fields in the hash. In such cases, we’re bound to get duplicates:
HRANDFIELD pet -10
Result:
1) "weight" 2) "age" 3) "height" 4) "height" 5) "color" 6) "color" 7) "height" 8) "color" 9) "color" 10) "height"
Include Field Values
By default, only the field names are returned (not the values). However, we can use the WITHVALUES
argument to include the actual values of the fields that are returned:
HRANDFIELD pet 1 WITHVALUES
Result:
1) "age" 2) "37"
When we use the WITHVALUES
argument, we need to also include the count
argument, even if we’re only getting one field. Here’s what happens if I remove the count
argument from the previous example:
HRANDFIELD pet WITHVALUES
Result:
(error) ERR value is not an integer or out of range
Passing the Wrong Number of Arguments
Passing the wrong number of arguments results in an error:
HRANDFIELD pet 2 WITHVALUES OOPS
Result:
(error) ERR syntax error
And calling the command without any arguments also results in an error:
HRANDFIELD
Result:
(error) ERR wrong number of arguments for 'hrandfield' command