XRANGE

从 ID 范围内的流中返回消息。

语法

XRANGE key start end [COUNT count]

引入版本：5.0.0

复杂度摘要：O(N)

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

XRANGE 命令有多种应用：

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

该命令还有一个倒数命令，以相反的顺序返回项目，称为 XREVRANGE，在其他方面是相同的。

必需参数

key

流键。

start

ID 范围的起始端（含）。使用 - 作为最小 ID。

end

ID 范围的末尾（含）。使用 + 作为最大 ID。

可选参数

COUNT count

返回的最大条目数。

示例

redis> XADD writers * name Virginia surname Woolf
"1784722084364-0"
redis> XADD writers * name Jane surname Austen
"1784722084364-1"
redis> XADD writers * name Toni surname Morrison
"1784722084365-0"
redis> XADD writers * name Agatha surname Christie
"1784722084366-0"
redis> XADD writers * name Ngozi surname Adichie
"1784722084366-1"
redis> XLEN writers
(integer) 5
redis> XRANGE writers - + COUNT 2
1) 1) "1784722084364-0"
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) "1784722084364-1"
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

详细说明

`-` 和 `+` 特殊 ID

The - and + special IDs mean respectively the minimum ID possible and the maximum ID possible inside a stream, so the following command will just return every entry in the stream:

> 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，但它们更易于键入。

身份证件不完整

Stream ID 由两部分组成，Unix 毫秒时间戳和同一毫秒内插入的条目的序列号。可以使用 XRANGE 仅指定 ID 的第一部分（毫秒时间），如下例所示：

> 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 的序列增加 1，从 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时，时间戳需要减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流简介。

Redis Software 与 Redis Cloud 兼容性

Redis 软件	Redis Cloud	说明
✅ 标准 ✅ 主动-主动	✅ 标准 ✅ 主动-主动

返回值

RESP2

数组回复：ID 与指定范围匹配的流条目列表。

RESP3