XRANGE

XRANGE key start end [COUNT count]

可用版本

Redis 开源版 5.0.0

时间复杂度

O(N)，其中 N 是返回的元素数量。如果 N 是常数（例如，始终使用 COUNT 请求前 10 个元素），则可以认为时间复杂度为 O(1)。

ACL 类别

@read, @stream, @slow,

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

XRANGE 命令有多种应用

• 返回特定时间范围内的项目。这是可能的，因为 Stream 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

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

> XRANGE somestream 1526985054069 1526985055069

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

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

排他范围

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

返回最大数量的条目

使用 COUNT 选项可以减少报告的条目数量。即使它看起来只是一个次要功能，但这非常重要，因为它允许模拟诸如 *给我大于或等于以下 ID 的条目* 之类的操作。

> 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 Streams 介绍文档。

示例

RESP2/RESP3 回复

历史

• 从 Redis 6.2.0 版本开始：增加了排他范围。