W3cubDocs

XTRIM

XTRIM key MAXLEN [=|~] length

Available since 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.

XTRIM trims the stream to a given number of items, evicting older items (items with lower IDs) if needed. The command is conceived to accept multiple trimming strategies, however currently only a single one is implemented, which is MAXLEN, and works exactly as the MAXLEN option in XADD.

For example the following command will trim the stream to exactly the latest 1000 items:

XTRIM mystream MAXLEN 1000

By default, or when provided with the optional = argument, the command performs exact trimming. That means that the trimmed stream's length will be exactly the minimum between its original length and the specified maximum length.

It is possible to give the command in the following special form in order to make it more efficient:

XTRIM mystream MAXLEN ~ 1000

The ~ argument between the MAXLEN option and the actual count means that the user is not really requesting that the stream length is exactly 1000 items, but instead it could be a few tens of entries more, but never less than 1000 items. When this option modifier is used, the trimming is performed only when Redis is able to remove a whole macro node. This makes it much more efficient, and it is usually what you want.

Return value

Integer reply, specifically:

The command returns the number of entries deleted from the stream.

redis> XADD mystream * field1 A field2 B field3 C field4 D "1609093317278-0" redis> XTRIM mystream MAXLEN 2 (integer) 0 redis> XRANGE mystream - +

1) 1) "1609093317278-0"
2) 1) "field1"
2) "A"
3) "field2"
4) "B"
5) "field3"
6) "C"
7) "field4"
8) "D"

© 2009–2020 Salvatore Sanfilippo
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.
https://redis.io/commands/xtrim