original
http://redis.io/commands/zadd
Introduction
Add one or more members to a sorted set, or update its score if it already exists.
Adds one or more members to the sorted set, updating its score if the member already exists.
grammar
ZADD key [NX|XX] [CH] [INCR] score member [score member ...]
Version
Available since 1.2.0.
Available since version 1.2.0.
time complexity
Time complexity: O(log(N)) for each item added, where N is the number of elements in the sorted set.
O(log(N)): N is the number of members in the sorted set.
describe
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.
Adds all the specified members with the specified scores to the sorted set. Multiple score/member pairs can be added. If a specified member is already a member of the sorted set, its score is updated and the member is reinserted in the correct position to ensure accurate sorting.
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.
If the key does not exist, a new sorted set is created with the specified members, as if the sorted set were empty. Returns an error if the key already exists but is not a sorted set.
The score values should be the string representation of a double precision floating point number. +inf and -inf values are valid values as well.
Fraction is the string representation of a double-precision floating-point number. +inf and -inf are also valid values.
ZADD options
Redis 3.0.2 and above are supported.
ZADD supports a list of options, specified after the name of the key and before the first score argument. Options are:
- XX: Only update elements that already exist. Never add elements.
- NX: Don't update already existing elements. Always add new elements.
- CH: Modify 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 are new elements added and elements already existing for which the score was updated. So elements specified in the command line having 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.
ZADD supports a series of options, specified after the key name and before the first score parameter. Options include:
- XX: Only update elements that already exist. Elements are never added.
- NX: Do not update existing elements. Always add new elements.
- CH: Modify the return value, from the number of new elements added to the number of changed elements (CH is an abbreviation for changed). Changed elements include new elements added, as well as elements that already exist and whose scores are updated. Therefore, if the specified element score is equal to the original score of the element, then the element is not counted. Note: Normally, the return value of ZADD only counts the number of new elements added.
- INCR: When this option is specified, ZADD is like ZINCRBY. In this mode, only one score/member pair can be specified.
return value
Integer reply, specifically:
- The number of elements added to the sorted sets, not including elements already existing for which the score was updated.
If the INCR option is specified, the return value will be Bulk string reply:
- the new score of member (a double precision floating point number), represented as string.
Integer: The number of elements to add to the sorted set, excluding elements that already exist and whose scores are updated.
If the INCR option is specified, the return value is a string: the new fraction of the member (a double-precision floating-point number), expressed as a string.
history
>= 2.4: Accepts multiple elements. In Redis versions older than 2.4 it was possible to add or update a single member per call.
2.4 and above, this command can accept multiple elements. Versions prior to 2.4 can only add or update one member at a time.
example
redis> ZADD myzset 1 "one"
(integer) 1
redis> ZADD myzset 1 "uno"
(integer) 1
redis> ZADD myzset 2 "two" 3 "three"
(integer) 2
redis> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"
redis>