ZADD

将一个或多个成员添加到有序集合中，或更新他们的分数。如果键不存在，则创建该键。

语法

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

引入版本：1.2.0

复杂度摘要：O(log(N)

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

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

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

必需参数

key

保存有序集合的键的名称。

score member [score member ...]

要添加或更新的一对或多对分数成员。 score 是双精度浮点数。

可选参数

NX 和 XX 是互斥的，GT 和 LT 也是互斥的。

NX

只添加新成员；不更新现有成员。

XX

仅更新现有成员；不添加新成员。

GT

仅当新分数大于当前分数时才更新现有成员。不阻止添加新成员。

LT

仅当新分数低于当前分数时才更新现有成员。不阻止添加新成员。

CH

将返回值从添加的成员数更改为更改的成员数（添加加更新）。

INCR

将会员的分数增加 score，而不是设置它，行为与 ZINCRBY 类似。只能给出一对得分成员。

示例

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

详细说明

可以精确表达的整数分数范围

Redis有序集合使用双64位浮点数来表示分数。此格式精确表示 -(2^53) 和 +(2^53) 之间的整数（含）。实际上，您可以存储从 -9007199254740992 到 9007199254740992 的整数，而不会损失精度。 Redis 在内部以指数形式表示较大的整数和分数，因此您可能只能得到您设置的分数的近似值。

有序集合101

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

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

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

分数相同的元素

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

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

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

Redis Software 与 Redis Cloud 兼容性

Redis 软件	Redis Cloud	说明
✅ 标准 ✅ 主动-主动	✅ 标准 ✅ 主动-主动

返回值

RESP2

以下任一情况： * 无回复：如果由于与 XX/NX/LT/GT 选项之一冲突而中止操作。 * 整数回复：不使用CH选项时的新成员数量。 * 整数回复：使用CH选项时新增或更新的成员数量。 * 批量字符串回复：使用INCR选项时会员的更新分数。

RESP3

以下任一情况： * 空回复：如果由于与 XX/NX/LT/GT 选项之一冲突而中止操作。 * 整数回复：不使用CH选项时的新成员数量。 * 整数回复：使用CH选项时新增或更新的成员数量。 * 双重回复：使用INCR选项时会员的更新分数。

资料来源：Redis 官方 ZADD 文档；中文内容参考 Redis 文档许可。