ZADD(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ ZADD — the sorted-set glow-up command 💅

okay bestie, this is zadd(3valkey), straight out of the Valkey Command Manual. it adds members to a sorted set (or updates their scores), and if the key isn't there yet? it just makes one. iconic behavior honestly. 🫶

📜 NAME

zadd — adds one or more members to a sorted set, or updates their scores. also creates the key if it doesn't exist. it's giving "build the thing AND edit the thing" ✨

🎀 SYNOPSIS

ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]

💖 DESCRIPTION

so basically, it adds all the members you specify with the scores you specify to the sorted set that lives at key. you can throw in multiple score / member pairs at once, no problem. and if a member you named is already in the sorted set? its score gets updated, and the element gets reinserted at the right position so the ordering stays correct. slay. 🔥

if key does not exist, a brand new sorted set is created with the members you specified as its sole members — exactly like it was an empty sorted set to start with. but if the key exists and it does not hold a sorted set? an error is returned. no cap.

the score values should be the string representation of a double precision floating point number. +inf and -inf are valid values too, go off. 🌈

🧚 ZADD options

ZADD supports a list of options, and you put them after the name of the key and before the first score argument. the options are:

  • XX — only update elements that already exist. do not add new elements. it's giving "we only do glow-ups, no new arrivals" 🙅♀️
  • NX — only add new elements. do not update already existing elements. new besties only, the old ones stay exactly as they are 💖
  • LT — only update existing elements if the new score is less than the current score. this flag doesn't prevent adding new elements. ⬇️
  • GT — only update existing elements if the new score is greater than the current score. this flag doesn't prevent adding new elements. ⬆️
  • CH — modifies the return value from the number of new elements added to the total number of elements changed (CH is an abbreviation of changed). changed elements = new elements added plus elements that already existed and had their score updated. so elements you specified on the command line that have the same score as they had in the past are not counted. note: normally the return value of ZADD only counts the number of new elements added. 👑
  • INCR — when this option is specified, ZADD acts like ZINCRBY. only one score-element pair can be specified in this mode. one at a time, bestie 😌
note: the GT, LT and NX options are mutually exclusive. pick your fighter, you cannot have all three. 💀

🔢 Range of integer scores that can be expressed precisely

Sorted Sets use a double 64-bit floating point number to represent the score. on all the architectures we support, this is represented as an IEEE 754 floating point number, which is able to represent precisely integer numbers between -(2^53) and +(2^53) included. in more practical terms, all the integers between -9007199254740992 and 9007199254740992 are perfectly representable. larger integers, or fractions, are internally represented in exponential form — so it's possible that you get only an approximation of the decimal number, or of the very big integer, that you set as score. 🙈

🌸 Sorted sets 101

Sorted sets are sorted by their score in an ascending way. the same element only exists a single time — no repeated elements are permitted, periodt. the score can be modified both by ZADD (which updates the element score and, as a side effect, its position in the sorted set) and by ZINCRBY, which you can use to update the score relative to its previous value. ✨

the current score of an element can be retrieved using the ZSCORE command, which you can also use to verify if an element already exists or not.

for an introduction to sorted sets, see the data types page on sorted sets. 📚

🦋 Elements with the same score

while the same element can't be repeated in a sorted set (since every element is unique), it is possible to add multiple different elements having the same score. when multiple elements have the same score, they are ordered lexicographically — they're still ordered by score as a first key, but locally, all the elements with the same score are relatively ordered lexicographically. 💅

the lexicographic ordering used is binary: it compares strings as array of bytes.

if the user inserts all the elements in a sorted set with the same score (for example 0), all the elements of the sorted set are sorted lexicographically, and range queries on elements are possible using the command ZRANGEBYLEX. (note: it's also possible to query sorted sets by range of scores using ZRANGEBYSCORE.) 🌈

📬 REPLY

RESP2

any of the following:

  • valkey-protocol(7) Nil reply: if the operation was aborted because of a conflict with one of the XX/NX/LT/GT options.
  • valkey-protocol(7) Integer reply: the number of new members when the CH option is not used.
  • valkey-protocol(7) Integer reply: the number of new or updated members when the CH option is used.
  • valkey-protocol(7) Bulk string reply: the updated score of the member when the INCR option is used.

RESP3

any of the following:

  • valkey-protocol(7) Null reply: if the operation was aborted because of a conflict with one of the XX/NX/LT/GT options.
  • valkey-protocol(7) Integer reply: the number of new members when the CH option is not used.
  • valkey-protocol(7) Integer reply: the number of new or updated members when the CH option is used.
  • valkey-protocol(7) Double reply: the updated score of the member when the INCR option is used.

⚡ COMPLEXITY

O(log(N)) for each item added, where N is the number of elements in the sorted set. fast. ate. left no crumbs. 🔥

🔐 ACL CATEGORIES

@fast @sortedset @write

📖 HISTORY

  • available since: 1.2.0 👶
  • changed in 2.4.0: accepts multiple elements.
  • changed in 3.0.2: added the XX, NX, CH and INCR options.
  • changed in 6.2.0: added the GT and LT options.

🍓 EXAMPLES

127.0.0.1:6379> ZADD myzset 1 "one"
(integer) 1
127.0.0.1:6379> ZADD myzset 1 "uno"
(integer) 1
127.0.0.1:6379> ZADD myzset 2 "two" 3 "three"
(integer) 2
127.0.0.1:6379> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"

look at that ordering. sorted by score, ties broken lexicographically. absolutely ate. 👑

👀 SEE ALSO

bzmpop(3valkey), bzpopmax(3valkey), bzpopmin(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), zunionstore(3valkey)

that's the whole vibe, bestie 🫶 this page is from Valkey version 9.0.0, dated 2025-10-21, and that's the <rainbow>ZADD(3valkey)</rainbow> moment. go forth and sort your sets. 💖✨🎀

📦 where this page comes from