Redis ZRANGESTORE Command Explained

In Redis, the ZRANGESTORE command works just like the ZRANGE command except that it stores the result in a key.

Basically, it allows us to get all members from a sorted set between a certain range and store them in a new key.

Syntax

The syntax goes like this:

ZRANGESTORE dst src min max [BYSCORE | BYLEX] [REV] [LIMIT offset count]

Example

Suppose we create a sorted set like this:

ZADD cats 15 Meow 27 Fluffy 43 Scratch 84 Purr 25 Bite 37 Bunting

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 ZRANGESTORE to get all contents of the sorted set and store them in a new key:

ZRANGESTORE cats2 cats 0 -1

Result:

(integer) 6

The min and max 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.

Let’s use the ZRANGE command to return the contents of the new key:

ZRANGE cats2 0 -1

Result:

1) "Meow"
2) "Bite"
3) "Fluffy"
4) "Bunting"
5) "Scratch"
6) "Purr"

We can use other negative values to specify an offset from the end of the sorted set. For example, a max 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 max argument:

ZRANGESTORE cats3 cats 1 4

Let’s check the contents of the new key:

ZRANGE cats3 0 -1

Result:

1) "Bite"
2) "Fluffy"
3) "Bunting"
4) "Scratch"

The BYSCORE Argument

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

ZRANGESTORE cats4 cats 25 43 BYSCORE

Result:

(integer) 4

And let’s check the contents of the new key, along with the scores:

ZRANGE cats4 0 -1 WITHSCORES

Result:

1) "Bite"
2) "25"
3) "Fluffy"
4) "27"
5) "Bunting"
6) "37"
7) "Scratch"
8) "43"

By default, the min and max arguments specify an inclusive range when using the BYSCORE argument. We can see this in the above example, where elements with scores of 25 and 43 were included in the results.

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

Here’s an example of what I mean:

ZRANGESTORE cats5 cats (25 (43 BYSCORE

Result:

(integer) 2

This time only two members were added to the new key. Let’s check:

ZRANGE cats5 0 -1 WITHSCORES

Result:

1) "Fluffy"
2) "27"
3) "Bunting"
4) "37"

So we can see that the members with 25 and 43 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 the -inf argument:

ZRANGESTORE cats6 cats -inf 30 BYSCORE

Result:

(integer) 3

Let’s check the key:

ZRANGE cats6 0 -1 WITHSCORES

Result:

1) "Meow"
2) "15"
3) "Bite"
4) "25"
5) "Fluffy"
6) "27"

As expected, it took everything up to 30 (although the highest score in our case was 27).

The REV Argument

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

ZRANGESTORE cats7 cats 43 25 BYSCORE REV

Result:

(integer) 4

Note that I put the 43 before the 25 this time, due to it being in reverse order.

Let’s check the new key:

ZRANGE cats7 0 -1 WITHSCORES

Result:

1) "Bite"
2) "25"
3) "Fluffy"
4) "27"
5) "Bunting"
6) "37"
7) "Scratch"
8) "43"

The LIMIT Argument

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

ZRANGESTORE cats8 cats -inf inf BYSCORE LIMIT 2 3

Result:

(integer) 3

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).

Let’s check the new key:

ZRANGE cats8 0 -1 WITHSCORES

Result:

1) "Fluffy"
2) "27"
3) "Bunting"
4) "37"
5) "Scratch"
6) "43"

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

The BYLEX Argument

The BYLEX argument causes ZRANGESTORE to select its members like the (now deprecated) ZRANGEBYLEX command. That is, it selects the range of elements from the sorted set between the min and max lexicographical closed range intervals. This relies on all elements having the same score.

Suppose we create the following sorted set:

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

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

ZRANGESTORE myzset2 myzset - [c BYLEX

Result:

(integer) 3

Let’s check the key:

ZRANGE myzset2 0 -1

Result:

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

When using the BYLEX argument, the min and max 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 max argument starts with [, which makes it inclusive, meaning that c is included.

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

ZRANGESTORE myzset3 myzset - (c BYLEX

Result:

(integer) 2

Let’s check the contents:

ZRANGE myzset3 0 -1

Result:

1) "a"
2) "b"

Here’s another example:

ZRANGESTORE myzset4 myzset [aa (g BYLEX

Result:

(integer) 5

And its contents:

ZRANGE myzset4 0 -1

Result:

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