Adds one or more members to a sorted set, or updates their scores. Creates the key if it doesn’t exist.
ZADD
key
[NX
| XX
]
[GT
| LT
]
[CH
] [INCR
]
score member [score member …]
Adds all the specified members with the specified scores to the
sorted set stored at key
. It is possible to specify
multiple score / member pairs. If a specified member is already a member
of the sorted set, the score is updated and the element reinserted at
the right position to ensure the correct ordering.
If key
does not exist, a new sorted set with the
specified members as sole members is created, like if the sorted set was
empty. If the key exists but does not hold a sorted set, an error is
returned.
The score values should be the string representation of a double
precision floating point number. +inf
and -inf
values are valid values as well.
ZADD supports a list of options, specified after the name of the key and before the first score argument. Options are:
ZADD
only
counts the number of new elements added.ZADD
acts like ZINCRBY
. Only one score-element
pair can be specified in this mode.Note: The GT, LT and NX options are mutually exclusive.
Sorted Sets use a double 64-bit floating point number to
represent the score. In all the architectures we support, this is
represented as an IEEE 754 floating point number, that
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 is
possible that you get only an approximation of the decimal number, or of
the very big integer, that you set as score.
Sorted sets are sorted by their score in an ascending way. The same
element only exists a single time, no repeated elements are permitted.
The score can be modified both by ZADD
that will update the
element score, and as a side effect, its position on the sorted set, and
by ZINCRBY
that can be used in order to update the score
relatively to its previous value.
The current score of an element can be retrieved using the
ZSCORE
command, that can also be used to verify if an
element already exists or not.
For an introduction to sorted sets, see the data types page on sorted sets.
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 are still ordered by score as a first key, however, 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 is also possible to query
sorted sets by range of scores using ZRANGEBYSCORE
).
Any of the following:
Nil reply: if the operation was aborted because of a conflict with one of the XX/NX/LT/GT options.
Integer reply: the number of new members when the CH option is not used.
Integer reply: the number of new or updated members when the CH option is used.
Bulk string reply: the updated score of the member when the INCR option is used.
Any of the following:
Null reply: if the operation was aborted because of a conflict with one of the XX/NX/LT/GT options.
Integer reply: the number of new members when the CH option is not used.
Integer reply: the number of new or updated members when the CH option is used.
Double reply: the updated score of the member when the INCR option is used.
O(log(N)) for each item added, where N is the number of elements in the sorted set.
@fast @sortedset @write
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"
XX
, NX
, CH
and INCR
options.GT
and LT
options.BZMPOP, BZPOPMAX, BZPOPMIN, ZCARD, ZCOUNT, ZDIFF, ZDIFFSTORE, ZINCRBY, ZINTER, ZINTERCARD, ZINTERSTORE, ZLEXCOUNT, ZMPOP, ZMSCORE, ZPOPMAX, ZPOPMIN, ZRANDMEMBER, ZRANGE, ZRANGESTORE, ZRANK, ZREM, ZREMRANGEBYLEX, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, ZREVRANK, ZSCAN, ZSCORE, ZUNION, ZUNIONSTORE.