XTRIM

从流的开头删除消息。

语法

XTRIM key [= | ~] threshold [LIMIT count] [KEEPREF | DELREF | ACKED]

引入版本：5.0.0

复杂度摘要：O(N)

如果需要，XTRIM 通过驱逐较旧的条目（具有较低 ID 的条目）来修剪流。

必需参数

key

流键的名称。

MAXLEN | MINID

修剪策略： - MAXLEN：只要流的长度超过指定阈值就驱逐条目 - MINID：驱逐 ID 低于指定阈值的条目（自 Redis 6.2.0 起可用）

threshold

修剪阈值： - 对于 MAXLEN：threshold 是一个非负整数，指定修剪后流中可以保留的最大条目数。 Redis 通过删除最旧的条目（即具有最低流 ID 的条目）来强制执行此操作，以便仅保留最新的条目。 - 对于 MINID：threshold 是流 ID。所有 ID 小于 threshold 的条目都会被修剪。所有 ID 大于或等于 threshold 的条目都会被保留。

可选参数

= | ~

修剪运算符： - =：精确修剪（默认） - 修剪到精确阈值 - ~：近似修剪 - 更高效，可能会留下比阈值稍多的条目

LIMIT count

限制修剪期间要检查的条目数量。从 Redis 6.2.0 开始可用。如果未指定，Redis 使用默认值 100 * 宏节点中的条目数。指定 0 会完全禁用限制机制。

KEEPREF | DELREF | ACKED

Specifies how to handle consumer group references when trimming. If there are no consumer groups, these arguments have no effect.从 Redis 8.2 开始可用。

如果不指定选项，则默认使用KEEPREF。与需要这些选项之一的 XDELEX 和 XACKDEL 命令不同，这里它们是可选的以保持向后兼容性：

KEEPREF（默认）：修剪时，根据指定的策略（MAXLEN 或 MINID）从流中删除条目，无论它们是否被任何消费者组引用，但保留所有消费者组的 PEL（待处理条目列表）中对这些条目的现有引用。
DELREF：修剪时，根据指定的策略从流中删除条目，并从所有消费者组的 PEL 中删除对这些条目的所有引用。
ACKED：修剪时，仅删除所有消费者组读取并确认的条目。请注意，如果引用条目的数量大于 MAXLEN，修剪仍会在限制处停止。

例如，这会将流修剪为恰好最新的 1000 个项目：

XTRIM mystream MAXLEN 1000

在此示例中，Redis 逐出 ID 低于 649085820-0 的所有条目：

XTRIM mystream MINID 649085820

默认情况下，或者当您提供可选的 = 参数时，该命令将执行精确修剪。

根据策略的不同，精确调整意味着：

MAXLEN：修剪后的流的长度将恰好是其原始长度和指定的 threshold 之间的最小值。
MINID：流中最旧的 ID 将恰好是其原始最旧 ID 和指定的 threshold 之间的最大值。

近乎精确的修剪

由于精确修剪可能需要 Redis 服务器进行额外的工作，因此您可以提供可选的 ~ 参数以使其更加高效。

例如：

XTRIM mystream MAXLEN ~ 1000

The ~ argument between the MAXLEN strategy and the threshold means that you are requesting to trim the stream so its length is 至少 the threshold, but possibly slightly more. In this case, Redis stops trimming early when performance can be gained (for example, when a whole macro node in the data structure can't be removed).这使得修剪更加高效，并且这通常是您想要的，尽管在修剪之后，流可能比 threshold 多了几十个额外条目。

使用 ~ 时控制命令完成的工作量的另一种方法是 LIMIT 子句。当您使用它时，它指定将被驱逐的条目的最大 count 。当您不指定 LIMIT 和 count 时，Redis 隐式使用默认值 100 * 宏节点中的条目数作为 count。将值 0 指定为 count 将完全禁用限制机制。

示例

redis> XADD mystream * field1 A field2 B field3 C field4 D
"1784722085136-0"
redis> XTRIM mystream MAXLEN 2
(integer) 0
redis> XRANGE mystream - +
1) 1) "1784722085136-0"
   2) 1) "field1"
      2) "A"
      3) "field2"
      4) "B"
      5) "field3"
      6) "C"
      7) "field4"
      8) "D"

Redis Software 与 Redis Cloud 兼容性

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

返回值

RESP2

整数回复：从流中删除的条目数。

RESP3

整数回复：从流中删除的条目数。

资料来源：Redis 官方 XTRIM 文档；中文内容参考 Redis 文档许可。