ZADD

将所有指定的成员及其分数添加到存储在 key 中的有序集合。可以指定多个分数/成员对。如果指定成员已是有序集合的成员，则会更新其分数，并将其重新插入到正确的位置以确保正确的排序。

如果 key 不存在，则会创建一个新的有序集合，其中指定的成员作为唯一成员，就像该有序集合为空一样。如果键存在但未持有有序集合，则会返回错误。

分数的值应为双精度浮点数的字符串表示。+inf 和 -inf 值也是有效值。

ZADD 选项

ZADD 支持一系列选项，这些选项在键名之后和第一个分数参数之前指定。选项包括

• XX: 仅更新已存在的元素。不添加新元素。
• NX: 仅添加新元素。不更新已存在的元素。
• LT: 仅当新分数小于当前分数时才更新现有元素。此标志不阻止添加新元素。
• GT: 仅当新分数大于当前分数时才更新现有元素。此标志不阻止添加新元素。
• CH: 将返回值从新添加元素的数量修改为已更改元素的总数（CH 是 changed 的缩写）。已更改的元素包括新添加的元素和分数已更新的现有元素。因此，命令行中指定的分数与过去相同的元素不被计算在内。注意：通常 ZADD 的返回值仅计算新添加元素的数量。
• INCR: 当指定此选项时，ZADD 的行为类似于 ZINCRBY。在此模式下，只能指定一个分数-元素对。

注意：GT、LT 和 NX 选项是互斥的。

可精确表示的整数分数范围

有序集合使用双精度 64 位浮点数来表示分数。在我们支持的所有架构中，这都表示为 IEEE 754 浮点数，能够精确表示包括 -(2^53) 和 +(2^53) 之间的整数。更实际地说，-9007199254740992 到 9007199254740992 之间的所有整数都可以完美表示。更大的整数或分数在内部以指数形式表示，因此您可能只能获得所设置的十进制数或非常大的整数的近似值。

有序集合基础知识

有序集合按分数升序排序。同一元素只能存在一次，不允许重复元素。分数可以通过 ZADD 修改，它会更新元素分数，并作为副作用，改变其在有序集合中的位置；也可以通过 ZINCRBY 修改，它用于相对于其先前值更新分数。

可以使用 ZSCORE 命令检索元素的当前分数，该命令也可用于验证元素是否已存在。

有关有序集合的介绍，请参阅数据类型页面中的有序集合部分。

分数相同的元素

虽然同一元素不能在有序集合中重复（因为每个元素都是唯一的），但可以添加多个具有相同分数的不同元素。当多个元素具有相同分数时，它们会按字典顺序排序（它们首先仍按分数排序，但在局部，所有分数相同的元素都相对按字典顺序排序）。

所使用的字典顺序是二进制的，它将字符串作为字节数组进行比较。

如果用户将有序集合中的所有元素都插入相同的分数（例如 0），则有序集合的所有元素都将按字典顺序排序，并且可以使用 ZRANGEBYLEX 命令对元素进行范围查询（注意：也可以使用 ZRANGEBYSCORE 通过分数范围查询有序集合）。

示例

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"

RESP2 回复

以下任意一种

• Nil 回复: 如果操作因与 XX/NX/LT/GT 选项之一冲突而被中止。

• 整数回复: 当未使用 CH 选项时，新成员的数量。

• 整数回复: 当使用 CH 选项时，新成员或已更新成员的数量。

• 批量字符串回复: 当使用 INCR 选项时，成员的更新分数。

RESP3 回复

以下任意一种

• Null 回复: 如果操作因与 XX/NX/LT/GT 选项之一冲突而被中止。

• 整数回复: 当未使用 CH 选项时，新成员的数量。

• 整数回复: 当使用 CH 选项时，新成员或已更新成员的数量。

• Double 回复: 当使用 INCR 选项时，成员的更新分数。

历史