XRANGE

XRANGE key start end [COUNT count]

可用版本

5.0.0

时间复杂度

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

ACL 类别

@read, @stream, @slow,

该命令返回与给定 ID 范围匹配的流条目。范围由最小 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 毫秒时间戳和一个在同一毫秒内插入的条目的序列号。可以使用 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 的序列从 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 响应

历史

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