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