ZADD

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

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

ZADD 命令的时间复杂度为 O(log(N))，其中 N 是有序集合中的元素数量。

Redis 原生命令语法

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

参数说明

• key: 有序集合的键
• NX: 仅添加新元素，不更新已存在的元素
• XX: 仅更新已存在的元素，不添加新元素
• LT: 仅当新分数小于当前分数时才更新现有元素
• GT: 仅当新分数大于当前分数时才更新现有元素
• CH: 修改返回值为变更元素的数量，而不是新增元素的数量
• INCR: 当此选项被指定时，ZADD 行为类似于 ZINCRBY
• score: 成员的分数
• member: 成员名称

详细说明

基本用法

ZADD 命令将成员添加到有序集合中，并为每个成员分配一个分数。有序集合中的成员按照分数升序排列。

ZADD myzset 1 "one"
ZADD myzset 1 "uno"
ZADD myzset 2 "two" 3 "three"

ZADD 选项

ZADD 支持多个选项，这些选项在键名之后、第一个分数参数之前指定：

• XX: 仅更新已存在的元素，不添加新元素
• NX: 仅添加新元素，不更新已存在的元素
• LT: 仅当新分数小于当前分数时才更新现有元素（不阻止添加新元素）
• GT: 仅当新分数大于当前分数时才更新现有元素（不阻止添加新元素）
• CH: 修改返回值为变更元素的总数（包括新增和更新的元素）
• INCR: 此选项指定 ZADD 行为类似于 ZINCRBY，只能指定一个分数-元素对

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

分数精度

Redis 有序集合使用双精度 64 位浮点数表示分数。在所有支持的架构中，这被表示为 IEEE 754 浮点数，能够精确表示 -(2^53) 到 +(2^53) 范围内的整数。

相同分数的元素

虽然同一个元素在有序集合中不能重复，但可以添加多个具有相同分数的不同元素。当多个元素具有相同分数时，它们按字典序排列。

Redisun 使用方式

在 redisun 中，ZADD 命令通过 ZAddCommand 类和 Redisun 类中的 zadd 方法实现。

基本用法

Redisun redisun = Redisun.create(options -> {
  options.setHost("localhost");
  options.setPort(6379);
});

// 添加单个成员到有序集合
int addedCount = redisun.zadd("myzset", 1.0, "member1");

// 添加多个成员
redisun.zadd("myzset", 1.0, "member1");
redisun.zadd("myzset", 2.5, "member2");
redisun.zadd("myzset", 3.7, "member3");

异步用法

// 异步添加成员到有序集合
CompletableFuture<Integer> future = redisun.asyncZadd("myzset", 1.0, "member1");

// 处理异步结果
future.thenAccept(addedCount -> {
  System.out.println("Added " + addedCount + " members");
});

注意事项

1. 分数值应该是双精度浮点数的字符串表示
2. +inf 和 -inf 值也是有效的分数值
3. 有序集合中的每个元素都是唯一的，但可以有相同的分数
4. 具有相同分数的元素按字典序排序

参考资料

• Redis ZADD 命令官方文档