Deletes messages from the beginning of a stream.
XTRIM
key
<MAXLEN
|
MINID
> [=
| ~
] threshold
[LIMIT
count]
XTRIM
trims the stream by evicting older entries
(entries with lower IDs) if needed.
Trimming the stream can be done 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 will trim the stream to exactly the latest 1000 items:
XTRIM mystream MAXLEN 1000
Whereas in this example, all entries that have an ID lower than 649085820-0 will be evicted:
XTRIM mystream MINID 649085820
By default, or when provided with 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
.Because exact trimming may require additional effort from the Valkey
server, the optional ~
argument can be provided to make it
more efficient.
For example:
XTRIM mystream MAXLEN ~ 1000
The ~
argument between the MAXLEN
strategy
and the threshold
means that the user is requesting to trim
the stream so its length is at least the
threshold
, but possibly slightly more. In this case, Valkey
will stop 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 few tens of additional
entries over the threshold
.
Another way to control the amount of work done by the command when
using the ~
, is the LIMIT
clause. When used,
it specifies the maximal count
of entries that will be
evicted. When LIMIT
and count
aren’t
specified, the default value of 100 * the number of entries in a macro
node will be implicitly used as the count
. Specifying the
value 0 as count
disables the limiting mechanism
entirely.
Integer reply: The number of entries deleted from the stream.
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.
@slow @stream @write
127.0.0.1:6379> XADD mystream * field1 A field2 B field3 C field4 D
"1714701492231-0"
127.0.0.1:6379> XTRIM mystream MAXLEN 2
(integer) 0
127.0.0.1:6379> XRANGE mystream - +
1) 1) "1714701492231-0"
2) 1) "field1"
2) "A"
3) "field2"
4) "B"
5) "field3"
6) "C"
7) "field4"
8) "D"
MINID
trimming strategy and the
LIMIT
option.XACK, XADD, XAUTOCLAIM, XCLAIM, XDEL, XGROUP, XGROUP CREATE, XGROUP CREATECONSUMER, XGROUP DELCONSUMER, XGROUP DESTROY, XGROUP HELP, XGROUP SETID, XINFO, XINFO CONSUMERS, XINFO GROUPS, XINFO HELP, XINFO STREAM, XLEN, XPENDING, XRANGE, XREAD, XREADGROUP, XREVRANGE, XSETID.