XTRIM

Syntax
XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT count] [KEEPREF
  | DELREF | ACKED]
Available since:
Redis Open Source 5.0.0
Time complexity:
O(N), with N being the number of evicted entries. Constant times are very small however, since entries are organized in macro nodes containing multiple entries that can be released with a single deallocation.
ACL categories:
@write, @stream, @slow,

XTRIM trims the stream by evicting older entries (entries with lower IDs) if needed.

Required arguments

key

The name of the stream key.

MAXLEN | MINID

The trimming strategy:

  • MAXLEN: Evicts entries as long as the stream's length exceeds the specified threshold
  • MINID: Evicts entries with IDs lower than the specified threshold (available since Redis 6.2.0)
threshold

The trimming threshold. For MAXLEN, this is a positive integer representing the maximum number of entries. For MINID, this is a stream ID.

Optional arguments

= | ~

The trimming operator:

  • =: Exact trimming (default) - trims to the exact threshold
  • ~: Approximate trimming - more efficient, may leave slightly more entries than the threshold
LIMIT count

Limits the number of entries to examine during trimming. Available since Redis 6.2.0. When not specified, Redis uses a default value of 100 * the number of entries in a macro node. Specifying 0 disables the limiting mechanism entirely.

KEEPREF | DELREF | ACKED

Specifies how to handle consumer group references when trimming. If no option is specified, KEEPREF is used by default:

  • KEEPREF (default): When trimming, removes entries from the stream according to the specified strategy (MAXLEN or MINID), regardless of whether they are referenced by any consumer groups, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).
  • DELREF: When trimming, removes entries from the stream according to the specified strategy and also removes all references to these entries from all consumer groups' PEL.
  • ACKED: When trimming, only removes entries that were read and acknowledged by all consumer groups. Note that if the number of referenced entries is larger than MAXLEN, trimming will still stop at the limit.

You can trim the stream using one of these strategies:

  • MAXLEN: Evicts entries as long as the stream's length exceeds the specified threshold, where threshold is a positive integer.
  • MINID: Evicts entries with IDs lower than threshold, where threshold is a stream ID.

For example, this trims the stream to exactly the latest 1000 items:

XTRIM mystream MAXLEN 1000

In this example, Redis evicts all entries that have an ID lower than 649085820-0:

XTRIM mystream MINID 649085820

By default, or when you provide the optional = argument, the command performs exact trimming.

Depending on the strategy, exact trimming means:

  • MAXLEN: The trimmed stream's length will be exactly the minimum between its original length and the specified threshold.
  • MINID: The oldest ID in the stream will be exactly the maximum between its original oldest ID and the specified threshold.

Nearly exact trimming

Because exact trimming may require additional effort from the Redis server, you can provide the optional ~ argument to make it more efficient.

For example:

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 at least 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). This makes trimming much more efficient, and it is usually what you want, although after trimming, the stream may have a few tens of additional entries over the threshold.

Another way to control the amount of work done by the command when using ~ is the LIMIT clause. When you use it, it specifies the maximum count of entries that will be evicted. When you don't specify LIMIT and count, Redis implicitly uses the default value of 100 * the number of entries in a macro node as the count. Specifying the value 0 as count disables the limiting mechanism entirely.

Examples

Return information

Integer reply: The number of entries deleted from the stream.

History

  • Starting with Redis version 6.2.0: Added the MINID trimming strategy and the LIMIT option.
  • Starting with Redis version 8.2.0: Added the KEEPREF, DELREF and ACKED options.