获取有序集合范围内的元素

ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count]
  [WITHSCORES]

自版本

1.2.0

时间复杂度

O(log(N)+M)，其中 N 是有序集合中的元素数量，M 是返回的元素数量。

ACL 类别

@read, @sortedset, @slow,

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

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

从 Redis 6.2.0 开始，该命令可以替换以下命令：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> 大于有序集合的结束索引，Redis 将使用有序集合的最后一个元素。

得分范围

当提供 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 个字节之后，我们可以存储我们要索引的元素的值。

示例

以下使用 WITHSCORES 的示例显示了命令如何始终返回数组，但这次填充了 element_1、score_1、element_2、score_2、...、element_N、score_N。

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

RESP2/RESP3 回复

历史

• 从 Redis 6.2.0 版本开始：添加了 REV、BYSCORE、BYLEX 和 LIMIT 选项。