XTRIM
Introduction
In Dragonfly, as well as in Redis and Valkey, the XTRIM
command is used to manage the length of a stream by trimming entries.
It helps in controlling memory usage by removing old entries from the stream.
XTRIM
can be useful for applications like logging, where recent data is more critical than historical data.
Syntax
XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT count]
- Time complexity: O(N), with N being the number of evicted entries.
- ACL categories: @write, @stream, @slow
Parameter Explanations
key
: The key of the stream that you want to trim.MAXLEN
: Trims entries as long as the stream's length exceeds the specifiedthreshold
(a positive integer).MINID
: Trims entries with IDs lower thanthreshold
(a stream ID).=
: Ensures the trimming is precisely executed to the specified threshold.~
: Instructs the trimming operation to be nearly exact in order to improve performance.threshold
: The threshold, which is the number of entries forMAXLEN
or the entry ID forMINID
.LIMIT count
: Another way to control the amount of work done by the command when using the~
, is theLIMIT
clause. When used, it specifies the maximal count of entries that will be evicted. WhenLIMIT count
is not specified, the default value of 100 * the number of entries in a macro node will be implicitly used as the count. Specifying the value0
ascount
disables the limiting mechanism entirely.
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 andthreshold
.MINID
: the oldest ID in the stream will be exactly the maximum between its original oldest ID andthreshold
.
Return Values
- The command returns the number of entries removed from the stream.
Code Examples
Using MAXLEN
to Trim
Trim a stream to a maximum of three entries:
dragonfly$> XADD mystream * field1 value1
"1609459200000-0"
dragonfly$> XADD mystream * field2 value2
"1609459200001-0"
dragonfly$> XADD mystream * field3 value3
"1609459200002-0"
dragonfly$> XADD mystream * field4 value4
"1609459200003-0"
dragonfly$> XADD mystream * field5 value5
"1609459200004-0"
dragonfly$> XTRIM mystream MAXLEN 3
(integer) 2
Using MINID
to Trim
Remove all entries with IDs less than a specific timestamp:
dragonfly$> XADD mystream * field1 value1
"1609459200000-0"
dragonfly$> XADD mystream * field2 value2
"1609459200001-0"
dragonfly$> XADD mystream * field3 value3
"1609459200002-0"
dragonfly$> XTRIM mystream MINID "1609459200001-0"
(integer) 1
Nearly Exact Trimming with ~
Improve performance by approximating the trim operation:
dragonfly$> XADD mystream * field1 value1
"1609459200000-0"
dragonfly$> XADD mystream * field2 value2
"1609459200001-0"
dragonfly$> XADD mystream * field3 value3
"1609459200002-0"
dragonfly$> XADD mystream * field4 value4
"1609459200003-0"
dragonfly$> XADD mystream * field5 value5
"1609459200004-0"
dragonfly$> XTRIM mystream MAXLEN ~ 2
(integer) 0
Best Practices
- Use approximative trimming with
~
for better performance on large streams, when precision is not critical. - Regularly trim streams if your application generates a significant amount of data, to manage memory usage efficiently.
Common Mistakes
- Confusing
MAXLEN
andMINID
.MAXLEN
specifies a count of entries, whereasMINID
specifies an entry ID threshold. - Not considering the trade-off between approximation (
~
) and precision (=
) in terms of performance and accuracy.
FAQs
What happens if the stream is empty or the key does not exist?
If the stream is empty or the key does not exist, XTRIM
returns 0
since no entries are removed.
Can I use negative values for threshold
?
No, the threshold
value for MAXLEN
must be a positive integers, and the threshold
value for MINID
must be a valid ID.