ZRANGE

返回存储在 <key> 处的有序集合中指定范围的元素。

ZRANGE 可以执行不同类型的范围查询：按索引（排名）、按分数，或按字典顺序。

此命令可以替代以下命令：ZREVRANGE, ZRANGEBYSCORE, ZREVRANGEBYSCORE, ZRANGEBYLEX 和 ZREVRANGEBYLEX。

通用行为和选项

元素的顺序是从最低分数到最高分数。分数相同的元素按字典顺序排列。

可选的 REV 参数会反转排序，使元素从最高分数到最低分数排列，分数相同时则通过反向字典顺序解决。

可选的 LIMIT 参数可用于从匹配的元素中获取一个子范围（类似于 SQL 中的 SELECT LIMIT offset, count）。负的 <count> 值将返回从 <offset> 开始的所有元素。请记住，如果 <offset> 很大，有序集合需要遍历 <offset> 个元素才能到达要返回的元素，这可能导致 O(N) 的时间复杂度。

可选的 WITHSCORES 参数会在命令的回复中补充返回元素的得分。返回的列表包含 value1,score1,...,valueN,scoreN，而不是 value1,...,valueN。客户端库可以自由返回更合适的数据类型（建议：包含 (value, score) 数组/元组的数组）。

索引范围

默认情况下，此命令执行索引范围查询。<start> 和 <stop> 参数表示基于零的索引，其中 0 是第一个元素，1 是下一个元素，依此类推。这些参数指定一个包含范围，例如，ZRANGE myzset 0 1 将返回有序集合的第一个和第二个元素。

索引也可以是负数，表示从有序集合末尾开始的偏移量，其中 -1 是有序集合的最后一个元素，-2 是倒数第二个元素，依此类推。

超出范围的索引不会产生错误。

如果 <start> 大于有序集合的结束索引或 <stop>，则返回一个空列表。

如果 <stop> 大于有序集合的结束索引，Valkey 将使用有序集合的最后一个元素。

分数范围

当提供 BYSCORE 选项时，此命令的行为类似于 ZRANGEBYSCORE，并返回有序集合中分数等于或介于 <start> 和 <stop> 之间的元素范围。

<start> 和 <stop> 可以是 -inf 和 +inf，分别表示负无穷大和正无穷大。这意味着您无需知道有序集合中的最高或最低分数即可获取从某个分数开始或到某个分数为止的所有元素。

默认情况下，由 <start> 和 <stop> 指定的分数区间是闭区间（包含）。可以通过在分数前加上字符 ( 来指定开区间（不包含）。

例如

ZRANGE zset (1 5 BYSCORE

将返回所有分数满足 1 < score <= 5 的元素，而

ZRANGE zset (5 (10 BYSCORE

将返回所有分数满足 5 < score < 10 的元素（不包含 5 和 10）。

反向范围

使用 REV 选项会反转有序集合，此时索引 0 为分数最高的元素。

默认情况下，<start> 必须小于或等于 <stop> 才能返回任何结果。但是，如果选择了 BYSCORE 或 BYLEX 选项，<start> 将是需要考虑的最高分数，而 <stop> 将是需要考虑的最低分数，因此 <start> 必须大于或等于 <stop> 才能返回任何结果。

例如

ZRANGE zset 5 10 REV

将返回反向索引中介于索引 5 和 10 之间的元素。

ZRANGE zset 10 5 REV BYSCORE

将返回所有分数小于 10 且大于 5 的元素。

字典序范围

当使用 BYLEX 选项时，此命令的行为类似于 ZRANGEBYLEX，并返回有序集合中介于 <start> 和 <stop> 字典序闭区间之间的元素范围。

请注意，字典序排序依赖于所有元素具有相同的分数。当元素具有不同分数时，返回结果是未定义的。

有效的 <start> 和 <stop> 必须以 ( 或 [ 开头，分别指定范围区间是开区间还是闭区间。

<start> 和 <stop> 的特殊值 + 或 - 分别表示正无穷大和负无穷大的字符串，因此，例如命令 ZRANGE myzset - + BYLEX 保证返回有序集合中的所有元素，前提是所有元素具有相同的分数。

REV 选项反转 <start> 和 <stop> 元素的顺序，此时 <start> 必须在字典序上大于 <stop> 才能产生非空结果。

字符串的字典序比较

字符串作为字节的二进制数组进行比较。由于 ASCII 字符集的指定方式，这意味着通常也会以一种显而易见的字典方式比较普通的 ASCII 字符。但是，如果使用非纯 ASCII 字符串（例如，utf8 字符串），则情况并非如此。

然而，用户可以对编码后的字符串应用转换，以便插入到有序集合中的元素的第一部分能够按照用户对特定应用程序的要求进行比较。例如，如果我想添加字符串，这些字符串将以不区分大小写的方式进行比较，但在查询时仍想检索其真实大小写，我可以按以下方式添加字符串

ZADD autocomplete 0 foo:Foo 0 bar:BAR 0 zap:zap

由于每个元素中的第一个标准化部分（在冒号字符之前），我们强制进行给定的比较。然而，在使用 ZRANGE ... BYLEX 查询范围后，应用程序可以向用户显示冒号后的字符串的第二部分。

比较的二进制性质允许将有序集合用作通用索引，例如，元素的第一部分可以是 64 位大端序数字。由于大端序数字将最高有效字节放在初始位置，因此二进制比较将与数字的数值比较匹配。这可以用于实现对 64 位值的范围查询。如下面的示例所示，在前 8 个字节之后，我们可以存储我们正在索引的元素的值。

示例

127.0.0.1:6379> ZADD myzset 1 "one" 2 "two" 3 "three"
(integer) 3
127.0.0.1:6379> ZRANGE myzset 0 -1
1) "one"
2) "two"
3) "three"
127.0.0.1:6379> ZRANGE myzset 2 3
1) "three"
127.0.0.1:6379> ZRANGE myzset -2 -1
1) "two"
2) "three"

以下使用 WITHSCORES 的示例展示了此命令总是返回一个数组，但这次，数组中填充的是 element_1, score_1, element_2, score_2, ..., element_N, score_N。

127.0.0.1:6379> ZADD myzset 1 "one" 2 "two" 3 "three"
(integer) 3
127.0.0.1:6379> ZRANGE myzset 0 1 WITHSCORES
1) "one"
2) "1"
3) "two"
4) "2"

此示例展示了如何按分数查询有序集合，排除值 1 并直到无穷大，仅返回结果的第二个元素

127.0.0.1:6379> ZADD myzset 1 "one" 2 "two" 3 "three"
(integer) 3
127.0.0.1:6379> ZRANGE myzset (1 +inf BYSCORE LIMIT 1 1
1) "three"

RESP2/RESP3 回复

数组回复：指定范围内的成员列表，当给定 WITHSCORES 选项时，可选地包含它们的分数。

历史