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

Redis ZADD 命令用于将一个或多个 member 元素及其 score 值加入到有序集 key 当中。

如果某个 member 已经是有序集的成员，那么更新这个 member 的 score 值，并通过重新插入这个 member 元素，来保证该 member 在正确的位置上。

如果有序集合 key 不存在，则创建一个空的有序集并执行 ZADD 操作。

当 key 存在但不是有序集类型时，返回一个错误。

score 值可以是整数值或双精度浮点数，score 可为正也可以为负。

对有序集的更多介绍请参见 sorted set 。

注意： 在 Redis 2.4 版本以前， ZADD 每次只能添加一个元素。

*语法

redis ZADD 命令基本语法如下：

redis 127.0.0.1:6379> ZADD key [NX|XX] [CH] [INCR] score member [score member …]

添加单个元素

redis> ZADD page_rank 10 google.com
(integer) 1

添加多个元素

redis> ZADD page_rank 9 baidu.com 8 redis.com.cn
(integer) 2

redis> ZRANGE page_rank 0 -1 WITHSCORES
1) "redis.com.cn"
2) "8"
3) "baidu.com"
4) "9"
5) "google.com"
6) "10"

添加已存在元素，且 score 值不变

redis> ZADD page_rank 10 google.com
(integer) 0

redis> ZRANGE page_rank 0 -1 WITHSCORES  # 没有改变
1) "redis.com.cn"
2) "8"
3) "baidu.com"
4) "9"
5) "google.com"
6) "10"

添加已存在元素，但是改变 score 值

redis> ZADD page_rank 6 redis.com.cn
(integer) 0

redis> ZRANGE page_rank 0 -1 WITHSCORES  # redis.com.cn 元素的 score 值被改变
1) "redis.com.cn"
2) "6"
3) "baidu.com"
4) "9"
5) "google.com"
6) "10"

*ZADD 参数

ZADD 支持参数，参数位于 key 名字和第一个 score 参数之间:

• XX: 仅更新存在的成员，不添加新成员。
• NX: 不更新存在的成员。只添加新成员。
• LT: 更新新的分值比当前分值小的成员，不存在则新增。
• GT: 更新新的分值比当前分值大的成员，不存在则新增。
• CH: 返回变更成员的数量。变更的成员是指 新增成员 和 score值更新的成员，命令指明的和之前score值相同的成员不计在内。 注意: 在通常情况下，ZADD返回值只计算新添加成员的数量。
• INCR: ZADD 使用该参数与 ZINCRBY 功能一样。一次只能操作一个score-element对。

注意: GT, LT 和 NX 三者互斥不能同时使用。

*scores 有效值范围

Redis 有序集合的分数使用双精度64位浮点数表示。在Redis所支持的平台上，称为IEEE 754 floating point number，它能包括的整数范围是-(2^53) 到 +(2^53)。或者说是-9007199254740992 到 9007199254740992。更大的整数在内部用指数形式表示，所以，如果为分数设置一个非常大的整数，你得到的是一个近似的十进制数。

*Sorted sets 101

有序集合按照分数以递增的方式进行排序。相同的成员（member）只存在一次，有序集合不允许存在重复的成员。 分数可以通过ZADD命令进行更新或者也可以通过ZINCRBY命令递增来修改之前的值，相应的他们的排序位置也会随着分数变化而改变。

获取一个成员当前的分数可以使用 ZSCORE 命令，也可以用它来验证成员是否存在。

更多关于有序集合的信息请参考 sorted sets.

*相同分数的成员

有序集合里面的成员是不能重复的都是唯一的，但是，不同成员间有可能有相同的分数。当多个成员有相同的分数时，他们将是按字典排序（ordered lexicographically）（仍由分数作为第一排序条件，然后，相同分数的成员按照字典序排序）。

字典顺序排序用的是二进制，它比较的是字符串的字节数组。

如果用户将所有元素设置相同分数（例如0），有序集合里面的所有元素将按照字典顺序进行排序，范围查询元素可以使用 ZRANGEBYLEX 命令（注：范围查询分数可以使用 ZRANGEBYSCORE 命令）。

*返回值

整数:

• 被成功添加的新成员的数量，不包括那些被更新分数的、已经存在的成员。

如果使用 INCR 选项，则返回 多行字符串:

• 以字符串形式表示的 member 的 score 值(双精度浮点数)。(双精度浮点数) , 执行失败返回 nil (当使用 XX 或 NX 选项)。

*历史

• >= 2.4: 支持一次增加或更新多个成员。
• >= 3.0.2: 增加 XX, NX, CH 和 INCR 选项。
• >=6.2: 增加 GT 和 LT 选项。

*例子

(integer) 1

(integer) 1

(integer) 2

1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"