In Redis, the ZUNION
command returns the union of the specified sorted sets.
Syntax
The syntax goes like this:
ZUNION numkeys key [key ...] [WEIGHTS weight [weight ...]]
[AGGREGATE <SUM | MIN | MAX>] [WITHSCORES]
The following examples demonstrate how the arguments are used.
Example
Suppose we create the following sorted sets:
ZADD cats 1 meow 2 fluffy 3 scratch
And:
ZADD dogs 1 bark 2 woof 3 fluffy 4 scratch
Let’s use the ZUNION
command to return the union of those two sorted sets:
ZUNION 2 cats dogs
Result:
1) "bark" 2) "meow" 3) "woof" 4) "fluffy" 5) "scratch"
As expected, it returned the union of the two given sorted sets. We can see that both fluffy
and scratch
appear in both sorted sets, but each of these only appear once in the result.
Include the Scores
We can use the WITHSCORES
argument to include the scores:
ZUNION 2 cats dogs WITHSCORES
Result:
1) "bark" 2) "1" 3) "meow" 4) "1" 5) "woof" 6) "2" 7) "fluffy" 8) "5" 9) "scratch" 10) "7"
By default, the scores for each member are added together from their respective sorted sets. In this example, fluffy
has a score of 5
(2
from cats
plus 3
from dogs
) and scratch has a score of 7
(3
from cats
and 4
from dogs
).
The AGGREGATE
Argument
In the previous example we saw how the scores were added together to produce an aggregate score. We can change this with the AGGREGATE
argument so that it returns either the minimum or maximum score from the original sorted set.
To do this we use the AGGREGATE
keyword followed by the option we want to use.
We can use MIN
for “minimum”:
ZUNION 2 cats dogs AGGREGATE MIN WITHSCORES
Result:
1) "bark" 2) "1" 3) "meow" 4) "1" 5) "fluffy" 6) "2" 7) "woof" 8) "2" 9) "scratch" 10) "3"
And MAX
for “maximum”:
ZUNION 2 cats dogs AGGREGATE MAX WITHSCORES
Result:
1) "bark" 2) "1" 3) "meow" 4) "1" 5) "woof" 6) "2" 7) "fluffy" 8) "3" 9) "scratch" 10) "4"
We can also explicitly state SUM
for the default behaviour of adding the scores:
ZUNION 2 cats dogs AGGREGATE SUM WITHSCORES
Result:
1) "bark" 2) "1" 3) "meow" 4) "1" 5) "woof" 6) "2" 7) "fluffy" 8) "5" 9) "scratch" 10) "7"
The WEIGHTS
Argument
We can use the WEIGHTS
argument to specify a multiplication factor for each input sorted set. This means that the score of every element in the input sorted set is multiplied by this factor before being passed to the aggregation function.
We can apply a different weighting to each sorted set.
Example:
ZUNION 2 cats dogs WEIGHTS 100 100 WITHSCORES
Result:
1) "bark" 2) "100" 3) "meow" 4) "100" 5) "woof" 6) "200" 7) "fluffy" 8) "500" 9) "scratch" 10) "700"
In this example, I specified that the members of both sets should be multiplied by 100 and the result reflects this.
Here’s an example of applying a different weighting to each set:
ZUNION 2 cats dogs WEIGHTS 100 200 WITHSCORES
Result:
1) "meow" 2) "100" 3) "bark" 4) "200" 5) "woof" 6) "400" 7) "fluffy" 8) "800" 9) "scratch" 10) "1100"
This time each element in the cats
sorted set was multiplied by 100, while each element in the dogs
sorted set was multiplied by 200.
The default multiplication factor is 1.
When the Keys Don’t Exist
If the keys don’t exist we get an empty array:
ZUNION 3 oops1 oops2 oops3
Result:
(empty array)
But if only one key exists, and it contains a sorted set, we get the members of that sorted set:
ZUNION 3 cats oops2 oops3
Result:
1) "meow" 2) "fluffy" 3) "scratch"
We can use the EXISTS
command to check for the existence of a key:
EXISTS oops1
Result:
(integer) 0
An integer reply of zero means that it doesn’t exist.
Wrong Data Type
If any of the keys contain the wrong data type, an error occurs:
ZUNION 2 countries places
Result:
(error) WRONGTYPE Operation against a key holding the wrong kind of value
In my case, the places
key contains a list and so we get the error.
We can use the TYPE
command to check the key’s data type:
TYPE places
Result:
list
As suspected, it’s a list.
Actually, the countries
key contains a set (not a sorted set) but it isn’t the culprit. Let’s check its type:
TYPE countries
Result:
set
The reason I say it’s not the culprit is because we can use it as the sole argument without any errors occurring:
ZUNION 1 countries
Result:
1) "Australia" 2) "New Zealand"
Conversely, if we pass the places
list as the sole argument, we get the error:
ZUNION 1 places
Result:
(error) WRONGTYPE Operation against a key holding the wrong kind of value