XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID> [= | ~] threshold [LIMIT count]] <* | id> field value [field value ...]
@write,
@stream,
@fast,
Appends the specified stream entry to the stream at the specified key.
If the key does not exist, XADD will create a new key with the given stream value as a side effect of running this command.
You can turn off key creation with the NOMKSTREAM option.
keyThe name of the stream key.
idThe stream entry ID. Use * to auto-generate a unique ID, or specify a well-formed ID in the format <ms>-<seq> (for example, 1526919030474-55).
field value [field value ...]One or more field-value pairs that make up the stream entry. You must provide at least one field-value pair.
NOMKSTREAMPrevents the creation of a new stream if the key does not exist. Available since Redis 6.2.0.
KEEPREF | DELREF | ACKEDSpecifies how to handle consumer group references when trimming. Available since Redis 8.2. If no option is specified, KEEPREF is used by default. Unlike the XDELEX and XACKDEL commands where one of these options is required, here they are optional to maintain backward compatibility:
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.MAXLEN | MINID [= | ~] threshold [LIMIT count]Trims the stream to maintain a specific size or remove old entries:
MAXLEN: Limits the stream to a maximum number of entriesMINID: Removes entries with IDs lower than the specified threshold (available since Redis 6.2.0)=: Exact trimming (default)~: Approximate trimming (more efficient)threshold: The maximum number of entries (for MAXLEN) or minimum ID (for MINID)LIMIT count: Limits the number of entries to examine during trimming (available since Redis 6.2.0)Each entry consists of a list of field-value pairs.
Redis stores the field-value pairs in the same order you provide them.
Commands that read the stream, such as XRANGE or XREAD, return the fields and values in exactly the same order you added them with XADD.
A stream entry ID identifies a specific entry inside a stream.
XADD auto-generates a unique ID for you if you specify the * character (asterisk) as the ID argument. However, you can also specify a well-formed ID to add the new entry with that exact ID, though this is useful only in rare cases.
Specify IDs using two numbers separated by a - character:
1526919030474-55
Both numbers are 64-bit integers. When Redis auto-generates an ID, the first part is the Unix time in milliseconds of the Redis instance generating the ID. The second part is a sequence number used to distinguish IDs generated in the same millisecond.
You can also specify an incomplete ID that consists only of the milliseconds part, which Redis interprets as a zero value for the sequence part.
To have only the sequence part automatically generated, specify the milliseconds part followed by the - separator and the * character:
> XADD mystream 1526919030474-55 message "Hello,"
"1526919030474-55"
> XADD mystream 1526919030474-* message " World!"
"1526919030474-56"
Redis guarantees that IDs are always incremental: the ID of any entry you insert will be greater than any previous ID, so entries are totally ordered inside a stream. To guarantee this property, if the current top ID in the stream has a time greater than the current local time of the instance, Redis uses the top entry time instead and increments the sequence part of the ID. This may happen when, for instance, the local clock jumps backward, or after a failover when the new master has a different absolute time.
When you specify an explicit ID to XADD, the minimum valid ID is 0-1, and you must specify an ID that is greater than any other ID currently inside the stream, otherwise the command fails and returns an error. Specifying explicit IDs is usually useful only if you have another system generating unique IDs (for instance an SQL table) and you want the Redis stream IDs to match those from your other system.
XADD incorporates the same semantics as the XTRIM command - refer to its documentation page for more information.
This allows you to add new entries and keep the stream's size in check with a single call to XADD, effectively capping the stream with an arbitrary threshold.
Although exact trimming is possible and is the default, due to the internal representation of streams, it is more efficient to add an entry and trim the stream with XADD using almost exact trimming (the ~ argument).
For example, calling XADD in the following form:
XADD mystream MAXLEN ~ 1000 * ... entry fields here ...
This adds a new entry but also evicts old entries so that the stream contains only 1000 entries, or at most a few tens more.
For more information about Redis streams, see the introduction to Redis Streams document.
| Redis Enterprise |
Redis Cloud |
Notes |
|---|---|---|
| ✅ Standard ✅ Active-Active |
✅ Standard ✅ Active-Active |
One of the following:
*) is passed as the id argument, otherwise the command just returns the same ID specified by the user during insertion.NOMKSTREAM option, MINID trimming strategy and the LIMIT option.<ms>-* explicit ID form.KEEPREF, DELREF and ACKED options.