Home / Tutorials / Redis / Sorted Set Data Structure

Redis Sorted Set Data Structure Tutorial

In this Redis tutorial we learn about the ordered version of a Set, sorted by scores.

We learn how to create a Sorted Set and how to use the various Sorted Set commands that Redis provides for us.

Redis Sorted Set Data Structure

Sorted sets in Redis are similar to regular Sets. The difference between them is that every member of a sorted set is associated with a score.

A score makes the sorted set ordered, from the smallest score to the greatest. As an example, consider an online game with a scoreboard that contains a player name associated with a score.

Because regular sets already use the “S” prefix, sorted sets use the “Z” prefix.

How to add items to a Sorted Set

To add items to a sorted set, we use the ZADD command.

The first argument is the sorted set’s name, followed by a score and the value associated with it.

Syntax: 
ZADD name score-1 value-1 score-2 value-2
Example: 
ZADD popular-dbs 1 mysql 2 mongodb 3 postgresql 4 redis

If the operation was successful it will show the number of elements added to the sorted set.

Output: 
(integer) 4

How to return the number of elements in a Sorted Set

The ZCARD command returns the number of elements present in the set.

The only argument is the sorted set name to check.

Syntax: 
ZCARD name
Example: 
ZCARD popular-dbs
Output: 
(integer) 4

The ZCOUNT command returns the number of elements within a range of scores.

Syntax: 
ZCOUNT name min max
Example: 
ZCOUNT popular-dbs 0 2
Output: 
(integer) 2

In this case it seems obvious that the returned number is 2, but let’s consider situations where the scores aren’t numbered in this way.

Example: 
ZADD sset 1 John 3 Jane 5 Jack 7 Jill

Now let’s count up to score 4.

Example: 
ZCOUNT sset sset 0 4
Output: 
(integer) 2

We can use our online game analogy again. We have only 10 players per match but the scores can number into thousands.

Let’s say we want to give our players bronze, silver and gold medals when they range between 999 - 1 000, 4 000 - 5 000 and 9 000 - 10 000+ respectively.

We would use ZCOUNT with those ranges to find the players so we could award them.

How to list the items in a Sorted Set

The ZRANGE command returns a specified range of the elements stored in a sorted set.

The elements are ordered from the lowest to the highest score and lexicographical (alphabetical) order is used when elements have the same exact score.

The first argument is the name of the sorted set, followed by the start and stop range we want to list.

Syntax: 
ZRANGE name start stop [WITHSCORES]
Example: 
ZRANGE popular-dbs 0 2

In the example above we list three out of the four elements in our sorted set, starting with the first (0) index.

Output: 
1) "mysql"
2) "mongodb"
3) "postgresql"

The range arguments can also be negative numbers, indicating offsets from the end of the sorted set, -1 being the last element, -2 the second to last element etc.

Example: 
ZRANGE popular-dbs 0 -1
Output: 
1) "mysql"
2) "mongodb"
3) "postgresql"
4) "redis"

The ZRANGE command has an optional argument, WITHSCORES . This allows us to return both the values and the scores.

Example: 
ZRANGE popular-dbs 0 -1 WITHSCORES

Redis will return the value, followed by the score associated with it.

Output: 
1) "mysql"
2) "1"
3) "mongodb"
4) "2"
5) "postgresql"
6) "3"
7) "redis"
8) "4"

The ZRANGEBYSCORE command will do the same thing as ZRANGE but we range through the scores instead of the values

Syntax: 
ZRANGEBYSCORE name start stop [WITHSCORES]

Because we now range by scores, negative offsets are not available. We won’t be able to use -1 etc.

Example: 
ZRANGEBYSCORE popular-dbs 0 3
Output: 
1) "mysql"
2) "mongodb"
3) "postgresql"

How to remove an element from a Sorted Set

The ZREM command will remove the specified element and its associated score from the sorted set.

The first argument is the name of the sorted set, followed by the value we want to remove.

With ZREM we remove by value and not by score. If we use the game analogy again, we would remove the element by the player name, not their score.

Syntax: 
ZREM name value
Example: 
ZREM popular-dbs redis

If the operation was successful it will return the number of elements removed.

If we return all the values in the sorted set, we will see that ‘redis’ has been removed.

Example: 
ZRANGE popular-dbs 0 -1
Output: 
1) "mysql"
2) "mongodb"
3) "postgresql"

How to return the rank of an element in a Sorted Set

The ZRANK command will return the rank of the element in the sorted set. We can also think of this as returning the index number.

The first argument is the name of the sorted set, followed by the element value.

Syntax: 
ZRANK name value
Example: 
ZRANK popular-dbs mysql
Output: 
(integer) 0

If we want to return the rank in reverse order, we use the ZREVRANK comand.

Example: 
ZREVRANK popular-dbs mysql
Output: 
(integer) 2

This time the output is 2, the last element in the sorted set.

How to return a score associated with a value

The ZSCORE command will return the score that’s associated with the specified value.

The first argument is the name of the sorted set, followed by the value.

Syntax: 
ZSCORE name value
Example: 
ZSCORE popular-dbs mongodb
Output: 
"2"
Previous
Set Data Structure
Next
Transactions