Redis ZDIFF Command Explained

In Redis, the ZDIFF command returns the difference between the first and all successive input sorted sets.

There’s also a ZDIFFSTORE command that stores the result in a key.

Syntax

The syntax for ZDIFF goes like this:

ZDIFF numkeys key [key ...] [WITHSCORES]

Example

Suppose we create two sorted sets, like this:

ZADD cats 1 meow 2 fluffy 3 scratch

And:

ZADD dogs 1 bark 2 woof

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

ZDIFF 2 cats dogs

Result:

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

That returns all the elements in the first set that aren’t in the second set. By this, I mean all elements whose values aren’t in the second set.

Let’s add an element to the dogs set:

ZADD dogs 3 fluffy

Now let’s run ZDIFF again:

ZDIFF 2 cats dogs

Result:

1) "meow"
2) "scratch"

This time only two elements are returned. That’s because fluffy appears in both sorted sets and ZDIFF 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 ZDIFF 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 ZDIFF against all three sets:

ZDIFF 3 cats dogs birds

Result:

1) "meow"

This time only one element is returned. 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.

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

The WITHSCORES Argument

The WITHSCORES argument can be used to output the scores of each element returned:

ZDIFF 2 cats dogs WITHSCORES

Result:

1) "meow"
2) "1"
3) "scratch"
4) "3"

Non-Existent Keys

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

ZDIFF 2 oops1 oops2

Result:

(empty array)

Here we got an empty array because none of the keys exist.

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

ZDIFF 3 cats oops1 oops2

Result:

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

All elements from the first set are returned because none of them 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:

ZDIFF 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):

ZDIFF 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):

ZDIFF 2 cats country

Result:

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

Here the country key contains a string.

However, the command does work on non-sorted sets:

ZDIFF 2 countries cats

Result:

1) "Australia"
2) "New Zealand"

In this case the countries key contains a (non-sorted) set.