XRANGE

Syntax

XRANGE key start end [COUNT count]

Available since:: 5.0.0
Time complexity:: O(N) with N being the number of elements being returned. If N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1).
ACL categories:: @read, @stream, @slow,

该命令返回与给定ID范围匹配的流条目。范围由最小和最大ID指定。所有ID在两个指定ID之间或恰好等于其中一个指定ID的条目（闭区间）将被返回。

XRANGE 命令有许多应用：

返回特定时间范围内的项目。这是可能的，因为流ID是与时间相关的。
逐步迭代流，每次迭代只返回少量项目。然而，它在语义上比SCAN系列函数更加健壮。
从流中获取单个条目，提供条目的ID以获取两次：作为查询间隔的开始和结束。

该命令还有一个返回相反顺序项的互逆命令，称为XREVRANGE，除此之外完全相同。

`-` 和 `+` 特殊ID

特殊ID - 和 + 分别表示流中可能的最小ID和最大ID，因此以下命令将返回流中的每个条目：

> XRANGE somestream - +
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"
2) 1) 1526985069902-0
   2) 1) "duration"
      2) "415"
      3) "event-id"
      4) "2"
      5) "user-id"
      6) "772213"
... other entries here ...

- 和 + 特殊ID分别表示最小和最大范围ID，不过它们更容易输入。

不完整的ID

流ID由两部分组成，一个是Unix毫秒时间戳，另一个是在同一毫秒内插入的条目的序列号。可以像以下示例中那样，仅指定ID的第一部分，即毫秒时间，来使用XRANGE：

> XRANGE somestream 1526985054069 1526985055069

在这种情况下，XRANGE 将自动补全开始间隔为 -0 和结束间隔为 -18446744073709551615，以便返回在给定毫秒和另一个指定毫秒之间生成的所有条目。这也意味着重复相同的毫秒两次，我们可以获取该毫秒内的所有条目，因为序列号范围将从零到最大值。

以这种方式使用XRANGE作为范围查询命令，以获取指定时间内的条目。这对于访问流中过去事件的历史记录非常方便。

独占范围

默认情况下，范围是闭合的（包含），这意味着回复可以包括与查询的开始和结束间隔匹配的ID条目。可以通过在ID前加上字符(来指定开放间隔（不包含）。这对于迭代流非常有用，如下所述。

返回最大条目数

使用COUNT选项可以减少报告的条目数量。这是一个非常重要的功能，即使它看起来可能微不足道，因为它允许，例如，模拟诸如给我大于或等于以下内容的条目的操作：

> XRANGE somestream 1526985054069-0 + COUNT 1
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"

在上述情况下，条目 1526985054069-0 存在，否则服务器会发送下一个条目。使用 COUNT 也是使用 XRANGE 作为迭代器的基础。

迭代流

为了迭代一个流，我们可以按照以下步骤进行。假设我们每次迭代需要两个元素。我们首先获取前两个元素，这很简单：

> XRANGE writers - + COUNT 2
1) 1) 1526985676425-0
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) 1526985685298-0
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

然后，我们不再从-开始迭代，而是使用前一次XRANGE调用返回的最后一个条目的ID作为范围的起始点，作为一个排他区间。

最后一个条目的ID是1526985685298-0，所以我们只需在其前面加上一个'('，然后继续我们的迭代：

> XRANGE writers (1526985685298-0 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
      3) "surname"
      4) "Morrison"
2) 1) 1526985712947-0
   2) 1) "name"
      2) "Agatha"
      3) "surname"
      4) "Christie"

依此类推。最终，这将允许访问流中的所有条目。显然，我们可以通过提供一个给定的不完整起始ID，从任何ID甚至特定时间开始迭代。此外，我们可以通过提供一个结束ID或不完整ID而不是+，将迭代限制到给定的ID或时间。

命令 XREAD 也能够迭代流。命令 XREVRANGE 可以反向迭代流，从较高的ID（或时间）到较低的ID（或时间）。

使用早期版本的Redis进行迭代

虽然独占范围间隔仅在Redis 6.2中可用，但仍然可以在早期版本中使用类似的流迭代模式。您可以从流中开始获取，如上所述，以获取第一个条目。

对于后续的调用，您需要以编程方式推进返回的最后一个条目的ID。大多数Redis客户端应该会抽象这个细节，但如果需要，也可以在应用程序中实现。在上面的例子中，这意味着将1526985685298-0的序列从0增加到1。因此，第二次调用将是：

> XRANGE writers 1526985685298-1 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
...

另外，请注意，一旦最后一个ID的序列部分等于18446744073709551615，您需要增加时间戳并将序列部分重置为0。例如，增加ID 1526985685298-18446744073709551615 应该得到 1526985685299-0。

对称的模式适用于使用XREVRANGE迭代流。唯一的区别是客户端需要为后续调用递减ID。当递减一个序列部分为0的ID时，时间戳需要减1，并将序列设置为18446744073709551615。

获取单个项目

如果你在寻找一个XGET命令，你可能会失望，因为XRANGE 实际上是获取流中单个条目的方法。你只需要在XRANGE的参数中指定ID两次即可：

> XRANGE mystream 1526984818136-0 1526984818136-0
1) 1) 1526984818136-0
   2) 1) "duration"
      2) "1532"
      3) "event-id"
      4) "5"
      5) "user-id"
      6) "7782813"

关于流的附加信息

有关Redis流的更多信息，请查看我们的 Redis流介绍文档。

示例

RESP2/RESP3 回复

Array reply: a list of stream entries with IDs matching the specified range.

历史

从 Redis 版本 6.2.0 开始：增加了独占范围。