SRANDMEMBER key [count]
- Available since:
- Time complexity:
- Without the count argument O(1), otherwise O(N) where N is the absolute value of the passed count.
- ACL categories:
When called with just the
key argument, return a random element from the set value stored at
If the provided
count argument is positive, return an array of distinct elements.
The array's length is either
count or the set's cardinality (
SCARD), whichever is lower.
If called with a negative
count, the behavior changes and the command is allowed to return the same element multiple times.
In this case, the number of returned elements is the absolute value of the specified
Bulk string reply: without the additional
count argument, the command returns a Bulk Reply with the randomly selected element, or
key does not exist.
Array reply: when the additional
count argument is passed, the command returns an array of elements, or an empty array when
key does not exist.
Specification of the behavior when count is passed
count argument is a positive value this command behaves as follows:
- No repeated elements are returned.
countis bigger than the set's cardinality, the command will only return the whole set without additional elements.
- The order of elements in the reply is not truly random, so it is up to the client to shuffle them if needed.
count is a negative value, the behavior changes as follows:
- Repeating elements are possible.
countelements, or an empty array if the set is empty (non-existing key), are always returned.
- The order of elements in the reply is truly random.
Distribution of returned elements
Note: this section is relevant only for Redis 5 or below, as Redis 6 implements a fairer algorithm.
The distribution of the returned elements is far from perfect when the number of elements in the set is small, this is due to the fact that we used an approximated random element function that does not really guarantees good distribution.
The algorithm used, that is implemented inside dict.c, samples the hash table buckets to find a non-empty one. Once a non empty bucket is found, since we use chaining in our hash table implementation, the number of elements inside the bucket is checked and a random element is selected.
This means that if you have two non-empty buckets in the entire hash table, and one has three elements while one has just one, the element that is alone in its bucket will be returned with much higher probability.
- Starting with Redis version 2.6.0: Added the optional