ZRANGE

ZRANGE 命令返回存储在键 key 的有序集合中，指定范围内的成员。

从 Redis 6.2.0 开始，ZRANGE 命令支持 BYSCORE、BYLEX 和 REV 选项，可以替代 ZREVRANGE、ZRANGEBYSCORE、ZREVRANGEBYSCORE、ZRANGEBYLEX 和 ZREVRANGEBYLEX 命令。

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

Redis 原生命令语法

ZRANGE key min max [BYSCORE|BYLEX] [REV] [WITHSCORES]

参数说明

• key: 有序集合的键
• min: 范围起始位置（包含），从 0 开始计数
• max: 范围结束位置（包含），可以使用负数表示从末尾开始计数
• BYSCORE: 按分数查询
• BYLEX: 按字典序查询
• REV: 倒序排列
• WITHSCORES: 可选参数，同时返回成员的分数

详细说明

ZRANGE 命令返回有序集合中指定范围内的成员，成员按照分数从低到高的顺序排列。下标参数 min 和 max 都以 0 为底，即 0 表示有序集合的第一个成员，1 表示第二个成员，以此类推。也可以使用负数下标，-1 表示最后一个成员，-2 表示倒数第二个成员，以此类推。

从 Redis 6.2.0 开始，ZRANGE 命令支持以下选项：

• BYSCORE: 按分数查询，此时 min 和 max 表示分数范围
• BYLEX: 按字典序查询，此时 min 和 max 表示字典序范围
• REV: 倒序排列，元素从最高分数到最低分数排序
• WITHSCORES: 同时返回成员的分数

返回值

• 如果没有指定 WITHSCORES 选项，返回指定范围内的成员列表
• 如果指定了 WITHSCORES 选项，返回成员和分数交替的列表

示例

redis> ZADD myzset 1 "one" 2 "two" 3 "three"
(integer) 3
redis> ZRANGE myzset 0 -1
1) "one"
2) "two"
3) "three"
redis> ZRANGE myzset 2 3
1) "three"
redis> ZRANGE myzset -2 -1
1) "two"
2) "three"
redis> ZRANGE myzset 0 1 WITHSCORES
1) "one"
2) "1"
3) "two"
4) "2"
redis> ZRANGE myzset 1 2 BYSCORE
1) "two"
2) "three"
redis> ZRANGE myzset 0 1 REV
1) "three"
2) "two"

Redisun 使用方式

在 redisun 中，ZRANGE 命令通过 ZRangeCommand 类和 Redisun 类中的 zrange 方法实现。

基本用法

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

// 添加一些测试数据
redisun.zadd("myzset", 1.0, "one");
redisun.zadd("myzset", 2.0, "two");
redisun.zadd("myzset", 3.0, "three");

// 获取所有成员
List<String> members = redisun.zrange("myzset", 0, -1);

// 获取指定范围的成员
List<String> rangeMembers = redisun.zrange("myzset", 0, 1);

// 获取指定范围的成员及其分数
List<String> membersWithScores = redisun.zrange("myzset", 0, 1, cmd -> cmd.withScores());

// 按分数范围查询
List<String> byScoreMembers = redisun.zrange("myzset", "1", "2", cmd -> cmd.byScore());

// 按字典序查询
List<String> byLexMembers = redisun.zrange("myzset", "[a", "[z", cmd -> cmd.byLex());

// 倒序排列
List<String> revMembers = redisun.zrange("myzset", 0, -1, cmd -> cmd.rev());

// 组合多个选项
List<String> revWithScores = redisun.zrange("myzset", 0, -1, cmd -> cmd.rev().withScores());

异步用法

// 异步获取成员
CompletableFuture<List<String>> future = redisun.asyncZrange("myzset", 0, -1);

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

// 异步获取成员及其分数
CompletableFuture<List<String>> futureWithScores = redisun.asyncZrange("myzset", 0, 1, cmd -> cmd.withScores());

// 处理异步结果
futureWithScores.thenAccept(membersWithScores -> {
  System.out.println("Members with scores: " + membersWithScores);
});

// 异步按分数范围查询
CompletableFuture<List<String>> futureByScore = redisun.asyncZrange("myzset", "1", "2", cmd -> cmd.byScore());

// 处理异步结果
futureByScore.thenAccept(members -> {
  System.out.println("Members by score: " + members);
});

注意事项

1. 范围参数超出有序集合范围时不会报错，会返回实际存在的成员
2. 起始位置大于结束位置时会返回空列表
3. 使用 WITHSCORES 选项时，返回结果中成员和分数交替出现

参考资料

• Redis ZRANGE 命令官方文档