ZUNIONSTORE(3valkey)

✨ ZUNIONSTORE ✨

okay bestie so this is a page from the Valkey Command Manual (that's the 3valkey manual, section 3) and we're about to talk about the union of sorted sets. yes THE union. sit down, grab a strawberry 🍓, it's gonna slay.

---

🌸 NAME 🌸

zunionstore — stores the union of multiple sorted sets in a key. 💖

---

🎀 SYNOPSIS 🎀

ZUNIONSTORE destination numkeys key [key...]  [WEIGHTS weight
[weight...]]  [AGGREGATE <SUM | MIN | MAX>]

---

🦋 DESCRIPTION 🦋

So what this does: it computes the union of numkeys sorted sets, the ones you name in the specified keys, and then it stores that result in destination. And bestie, it is mandatory to give the number of input keys (numkeys) before you pass the input keys and all the other optional args. no skipping that, the number comes first, periodt. 💅

By default, the resulting score of an element is just the sum of its scores in the sorted sets where it exists. simple. clean. iconic.

Then there's the WEIGHTS option, and this is where it gets fun: you can specify a multiplication factor for each input sorted set. meaning the score of every element in every input sorted set gets multiplied by that factor before it's handed over to the aggregation function. if WEIGHTS isn't given, the multiplication factors default to 1. (yes, 1, so nothing changes, she's just vibing. ✨)

With the AGGREGATE option you get to pick how the results of the union are aggregated. this defaults to SUM, where the score of an element is summed across the inputs where it exists. and when you set it to MIN or MAX instead, the resulting set contains the minimum or maximum score of an element across the inputs where it exists. choose your fighter. 👑

and if destination already exists? it gets overwritten. no warning, no mercy, she's gone. 💀

---

💌 REPLY 💌

valkey-protocol(7) integer reply: the number of elements in the resulting sorted set. a whole number, cute and tidy. 🔢

---

⚡ COMPLEXITY ⚡

O(N)+O(M log(M)) — with N being the sum of the sizes of the input sorted sets, and M being the number of elements in the resulting sorted set. math girlies rise. 🧚

---

🔐 ACL CATEGORIES 🔐

• @slow
• @sortedset
• @write

---

📜 HISTORY 📜

• Available since: 2.0.0 — she's an elder, she's been here, she's been doing this. 🌈

---

🙈 NOTES 🙈

okay so if you pass an option like WEIGHTS or AGGREGATE multiple times, it is undefined which option takes precedence. undefined!! meaning nobody knows!! don't do it, bestie, just say it once and move on. 😭

---

🌟 EXAMPLES 🌟

127.0.0.1:6379> ZADD zset1 1 "one"
(integer) 1
127.0.0.1:6379> ZADD zset1 2 "two"
(integer) 1
127.0.0.1:6379> ZADD zset2 1 "one"
(integer) 1
127.0.0.1:6379> ZADD zset2 2 "two"
(integer) 1
127.0.0.1:6379> ZADD zset2 3 "three"
(integer) 1
127.0.0.1:6379> ZUNIONSTORE out 2 zset1 zset2 WEIGHTS 2 3
(integer) 3
127.0.0.1:6379> ZRANGE out 0 -1 WITHSCORES
1) "one"
2) "5"
3) "three"
4) "9"
5) "two"
6) "10"

look at that output ate and left no crumbs 💅 "two" is sitting at "10" because 2*2 + 3*2 = 10, we love a weighted union moment.

---

👀 SEE ALSO 👀

the whole sorted-set friend group, no cap:

bzmpop(3valkey), bzpopmax(3valkey), bzpopmin(3valkey), zadd(3valkey), zcard(3valkey), zcount(3valkey), zdiff(3valkey), zdiffstore(3valkey), zincrby(3valkey), zinter(3valkey), zintercard(3valkey), zinterstore(3valkey), zlexcount(3valkey), zmpop(3valkey), zmscore(3valkey), zpopmax(3valkey), zpopmin(3valkey), zrandmember(3valkey), zrange(3valkey), zrangebylex(3valkey), zrangebyscore(3valkey), zrangestore(3valkey), zrank(3valkey), zrem(3valkey), zremrangebylex(3valkey), zremrangebyrank(3valkey), zremrangebyscore(3valkey), zrevrange(3valkey), zrevrangebylex(3valkey), zrevrangebyscore(3valkey), zrevrank(3valkey), zscan(3valkey), zscore(3valkey), zunion(3valkey)

---

okay that's the whole page, you're officially a zunionstore girly now 🫶 this was Valkey version 9.0.0, dated 2025-10-21, and that's the vibe check, we passed it. go union some sorted sets, bestie, you've got this. 💖✨🎀🦋🌸