In Redis, the ZDIFFSTORE command computes the difference between the first and all successive input sorted sets and stores the result in the specified key.

ZDIFFSTORE works in the same way as the ZDIFF command, except that it stores the result instead of returning it (ZDIFF returns the result instead of storing it in a new key).

Syntax

The syntax goes like this:

ZDIFFSTORE destination numkeys key [key ...]

Example

Suppose we create two sorted sets, like this:

ZADD cats 1 meow 2 fluffy 3 scratch

And:

ZADD dogs 1 bark 2 woof 3 fluffy

We can use the ZDIFFSTORE command against those two sorted sets like this:

ZDIFFSTORE result1 2 cats dogs

Result:

(integer) 2

That computed all the elements in the first set that aren’t in the second set and stored it in a key called result1. We got an integer reply of 2, which means that two elements were added to the resulting sorted set.

Let’s take a look at the new key:

ZRANGE result1 0 -1

Result:

1) "meow"
2) "scratch"

As expected, it only contains two elements. That’s because fluffy appears in both of the original sorted sets and ZDIFFSTORE only returns the difference between the first sorted set and all subsequent sorted sets.

The numkeys value of 2 in the above examples means that I’m providing two sets.

More Sorted Sets

The ZDIFFSTORE command allows us to include as many sorted sets as we want in our list. They are all compared to the first one and any difference between the first and subsequent sets are returned.

Let’s create another sorted set:

ZADD birds 1 tweet 2 scratch

Now let’s run ZDIFFSTORE against all three sets:

ZDIFFSTORE result2 3 cats dogs birds

Result:

(integer) 1

Note that the numkeys argument is now 3, which reflects the number of sorted sets I’m providing.

This time only one element is added to the new sorted set. That’s because the other elements from the cats set contain values that are also present in at least one of the other sorted sets. That is, the dogs set contains fluffy and the birds set contains scratch, both of which are in the cats set.

Let’s take a look at the new sorted set:

ZRANGE result2 0 -1

Result:

1) "meow"

Non-Existent Keys

Keys that don’t exist are treated as empty sets:

ZDIFFSTORE result3 2 oops1 oops2

Result:

(integer) 0

Nothing was added to the new key.

Let’s check the new key:

ZRANGE result3 0 -1

Result:

(empty array)

The key contains an empty array because none of the keys that we used with ZDIFFSTORE existed.

Here’s what happens when the first key exists, but none of the others do:

ZDIFFSTORE result4 3 cats oops1 oops2

Result:

(integer) 3

And take a look at the key:

ZRANGE result4 0 -1

Result:

1) "meow"
2) "fluffy"
3) "scratch"

All elements from the first set were added to the new key because none of those elements are present in any of the other (empty) sets.

Using the Wrong numkeys Argument

Here’s what happens when we use the wrong value for the numkeys argument:

ZDIFFSTORE result5 3 cats dogs

Result:

(error) ERR syntax error

In this case I specified that there would be three sorted sets to compare, but I only provided two.

The same error applies when it’s the other way around (i.e. I specify 2 but provide three keys):

ZDIFFSTORE result6 2 cats dogs birds

Result:

(error) ERR syntax error

Passing a Key of the Wrong Type

Here’s what happens when we pass a key that contains a different type (i.e. it’s not a sorted set):

ZDIFFSTORE result7 2 cats country

Result:

(error) WRONGTYPE Operation against a key holding the wrong kind of value

In this case, the country key contains a string.

However, it works fine on non-sorted sets:

ZDIFFSTORE result8 2 countries cats

Result:

(integer) 2

In this case the countries key contains a (non-sorted) set as follows:

ZRANGE result8 0 -1

Result:

1) "Australia"
2) "New Zealand"

When the Destination Key Already Exists

If the destination key already exists, it’s overwritten.

Let’s overwrite the result8 key from the previous example:

ZDIFFSTORE result8 2 cats dogs

Result:

(integer) 2

Check the contents:

ZRANGE result8 0 -1

Result:

1) "meow"
2) "scratch"

As expected, the result8 key has been overwritten with our new results.