In Redis, the ZRANDMEMBER command enables us to get one or more random elements from a sorted set.

We can specify whether or not to return only distinct elements or to allow duplicates. We can also specify whether or not to include the scores of each element in the result.

Syntax

The syntax goes like this:

ZRANDMEMBER key [count [WITHSCORES]]

Example

Suppose we create a sorted set like this:

ZADD scores 220 user:1 110 user:2 330 user:3 550 user:4 440 user:5 660 user:6

Result:

(integer) 6

In my case the sorted set didn’t exist, and so it was created and the six elements were added as specified.

Now let’s run ZRANDMEMBER against it:

ZRANDMEMBER scores

Result:

"user:5"

In this case I didn’t provide the count argument, and therefore only one element was randomly returned as a bulk string reply.

Let’s run the command multiple times:

3 ZRANDMEMBER scores

Result:

"user:2"
"user:1"
"user:6"

Here, I prefixed the command with the number of times I wanted it to run. This is a technique that we can do to run any command multiple times in the Redis CLI.

Return Multiple Random Elements

As mentioned, the ZRANDMEMBER command can return more than one random element from the sorted set. To do this, all we need to do is pass the count argument with the number of elements we want returned:

ZRANDMEMBER scores 3

Result:

1) "user:2"
2) "user:5"
3) "user:6"

When we do this, the random elements are returned in an array.

Include the Scores

We can use the WITHSCORES argument to include the scores of each element in the result:

ZRANDMEMBER scores 3 WITHSCORES

Result:

1) "user:2"
2) "110"
3) "user:5"
4) "440"
5) "user:6"
6) "660"

Allow Duplicates

Passing a negative count value to the command enables non-distinct elements to be returned:

ZRANDMEMBER scores -5

Result:

1) "user:5"
2) "user:3"
3) "user:3"
4) "user:5"
5) "user:1"

However, it doesn’t necessarily mean that the result will always include duplicate elements. Here’s what happens when I ran that code again:

ZRANDMEMBER scores -5

Result:

1) "user:5"
2) "user:2"
3) "user:1"
4) "user:3"
5) "user:4"

We can use the negative count to return more elements than exist in the sorted set:

ZRANDMEMBER scores -10

Result:

 1) "user:2"
 2) "user:6"
 3) "user:5"
 4) "user:4"
 5) "user:3"
 6) "user:6"
 7) "user:3"
 8) "user:2"
 9) "user:3"
10) "user:2"

Our sorted set only has six elements but we returned ten in this example. Doing this ensures that we get at least some duplicate values.

As mentioned, using a positive value will ensure that only distinct elements are returned. Therefore, if we use a count larger than the sorted set when using a positive count, the result will be limited to the number of elements in the sorted set:

ZRANDMEMBER scores 10

Result:

1) "user:6"
2) "user:4"
3) "user:5"
4) "user:3"
5) "user:1"
6) "user:2"

When the Key Doesn’t Exist

If the key doesn’t exist, the result depends on whether we are calling the command with the count argument or not.

Calling a non-existent key without the count argument results in nil:

ZRANDMEMBER oops

Result:

(nil)

Calling it with the count argument results in empty array:

ZRANDMEMBER oops 1

Result:

(empty array)

This is true even if we call it with a count of 1, as this example demonstrates.

Truly Random?

According to the Redis documentation:

• When using a positive count argument, the order of elements in the reply is not truly random.
• When using a negative count argument, the order of elements in the reply is truly random.