XTRIM(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 XTRIM — bestie edition (valkey command manual)

okay so you know how streams just keep growing forever and ever like my unread notifications? yeah. xtrim is the girl who comes in and clears out the old stuff from the front. she's from the valkey command manual and she's iconic, no cap. ✨

✨ SYNOPSIS ✨

XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT count]

🦋 DESCRIPTION 🦋

XTRIM trims the stream by evicting older entries (entries with lower IDs) if needed. that's it, that's the whole job. she's an eviction notice for the entries at the front of the line. 💀

you can trim using one of these two strategies, pick your fighter:

  • 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. she said precision, periodt.

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 Valkey server (she's doing the most, honestly), the optional ~ argument can be provided to make it more efficient. it's giving "close enough, bestie." 💅

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. not her being messy on purpose, it's a feature. 🫶

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. (yes, 0 = no cap on evictions. unhinged behaviour, but valid. 🔥)

💖 REPLY 💖

valkey-protocol(7) Integer reply: the number of entries deleted from the stream.

⭐ 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. she's efficient like that. ✨

👑 ACL CATEGORIES 👑

@slow @stream @write

🌈 HISTORY 🌈

  • available since: 5.0.0
  • changed in 6.2.0: added the MINID trimming strategy and the LIMIT option.

(the glow-up was real in 6.2.0, we love to see it.)

🎀 EXAMPLES 🎀

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"

🧚 SEE ALSO 🧚

xack(3valkey), xadd(3valkey), xautoclaim(3valkey), xclaim(3valkey), xdel(3valkey), xgroup(3valkey), xgroup-create(3valkey), xgroup-createconsumer(3valkey), xgroup-delconsumer(3valkey), xgroup-destroy(3valkey), xgroup-help(3valkey), xgroup-setid(3valkey), xinfo(3valkey), xinfo-consumers(3valkey), xinfo-groups(3valkey), xinfo-help(3valkey), xinfo-stream(3valkey), xlen(3valkey), xpending(3valkey), xrange(3valkey), xread(3valkey), xreadgroup(3valkey), xrevrange(3valkey), xsetid(3valkey)

and that's the tea, bestie 🍓 this whole page is straight out of valkey version 9.0.0, dated 2025-10-21, and it's giving main character energy from start to finish. go trim something. you got this. 💜🌸✨
📦 where this page comes from