In Redis, the ZRANGE command returns the specified range of elements in the sorted set stored at the specified key.

It can perform different types of range queries: by index (rank), by the score, or by lexicographical order.

Syntax

The syntax goes like this:

ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset 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.

Let’s use ZRANGE to return the contents of the sorted set:

ZRANGE scores 0 -1

Result:

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

The start and stop arguments are used to specify the range of elements to return. These represent zero-based indexes, and so in my case 0 specifies the first element. We can use -1 to specify the last element (which I did in this example). This enables us to return all elements without knowing how many elements are in the sorted set.

We can use other negative values to specify an offset from the end of the sorted set. For example, a stop argument of -2 specifies the second last element, -3 specifies the third last, and so on.

Here’s an example of using a positive value for the stop argument:

ZRANGE scores 1 4

Result:

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

The WITHSCORES Argument

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

ZRANGE scores 0 -1 WITHSCORES

Result:

 1) "user:2"
 2) "110"
 3) "user:1"
 4) "220"
 5) "user:3"
 6) "330"
 7) "user:5"
 8) "440"
 9) "user:4"
10) "550"
11) "user:6"
12) "660"

The BYSCORE Argument

We can use the BYSCORE argument to return elements based on their score. When we use this argument, the start and stop arguments represent the range of scores that the elements must contain to be included in the result.

ZRANGE scores 220 550 BYSCORE WITHSCORES

Result:

1) "user:1"
2) "220"
3) "user:3"
4) "330"
5) "user:5"
6) "440"
7) "user:4"
8) "550"

By default, the start and stop arguments specify an inclusive range when using the BYSCORE argument. We can see this in the above example, where elements with scores of 220 and 550 were included in the results.

However, we can make the range exclusive by prefixing the start and/or stop arguments with the ( character.

Here’s an example of what I mean:

ZRANGE scores (220 (550 BYSCORE WITHSCORES

Result:

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

This time the elements with 220 and 550 were excluded from the result.

We can use the -inf and inf arguments to denote the negative and positive infinities. This allows us to get all elements from or up to a certain score without having to know the highest or lowest score. Here’s an example that uses both of these arguments:

ZRANGE scores -inf inf BYSCORE WITHSCORES

Result:

 1) "user:2"
 2) "110"
 3) "user:1"
 4) "220"
 5) "user:3"
 6) "330"
 7) "user:5"
 8) "440"
 9) "user:4"
10) "550"
11) "user:6"
12) "660"

Here’s an example that uses one of those:

ZRANGE scores 400 inf BYSCORE WITHSCORES

Result:

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

The REV Argument

By default, the elements are sorted in ascending order. We can change this to descending order by using the REV argument:

ZRANGE scores 0 -1 REV WITHSCORES

Result:

 1) "user:6"
 2) "660"
 3) "user:4"
 4) "550"
 5) "user:5"
 6) "440"
 7) "user:3"
 8) "330"
 9) "user:1"
10) "220"
11) "user:2"
12) "110"

The LIMIT Argument

We can use the LIMIT argument to return a sub-range from the matching elements:

ZRANGE scores -inf inf BYSCORE LIMIT 2 3

Result:

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

In the above example, 2 is the offset (for where to start the sub-range) and 3 is the count (i.e. the number of elements to return).

The LIMIT argument can only be used when BYSCORE or BYLEX is used.

The BYLEX Argument

The BYLEX argument causes ZRANGE to behave like the (now deprecated) ZRANGEBYLEX command. That is, it returns the range of elements from the sorted set between the start and stop lexicographical closed range intervals. This relies on all elements having the same score.

Suppose we create the following sorted set:

ZADD testzset 0 a 0 b 0 c 0 d 0 e 0 f 0 g

Here’s an example of using ZRANGE with the BYLEX argument:

ZRANGE testzset - [c BYLEX

Result:

1) "a"
2) "b"
3) "c"

When using the BYLEX argument, the start and stop arguments must start with ( or [, in order to specify whether the range interval is exclusive or inclusive. The special values of + and - mean positive and negative infinite strings.

In the above example the stop argument starts with [, which makes it inclusive, meaning that c is included.

In the following example, we use ( to make it exclusive:

ZRANGE testzset - (c BYLEX

Result:

1) "a"
2) "b"

Here’s another example:

ZRANGE testzset [aa (g BYLEX

Result:

1) "b"
2) "c"
3) "d"
4) "e"
5) "f"

More Information

See the Redis documentation for more information about this command, including any changes that may have been implemented since this article was published.