XADD 

XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED]
  [IDMPAUTO producer-id | IDMP producer-id idempotent-id]
  [<MAXLEN | MINID> [= | ~] threshold [LIMIT count]] <* | id>
  field value [field value ...]
Available since:
Redis Open Source 5.0.0
Time complexity:
O(1) when adding a new entry, O(N) when trimming where N being the number of entries evicted.
ACL categories:
@write, @stream, @fast,
Compatibility:
Redis Software and Redis Cloud compatibility

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.

Required arguments

key

The name of the stream key.

id

The 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.

Optional arguments

NOMKSTREAM

Prevents the creation of a new stream if the key does not exist. Available since Redis 6.2.0.

IDMPAUTO producer-id | IDMP producer-id idempotent-id

Enables idempotent message processing (at-most-once production) to prevent duplicate entries. Available since Redis 8.6.

  • IDMPAUTO producer-id: Automatically generates a unique idempotent ID (iid) for the specified producer-id. Redis tracks this iid to prevent duplicate messages from the same producer-id.
  • IDMP producer-id idempotent-id: Uses the specified idempotent-id for the given producer-id. If this producer-id/idempotent-id combination was already used, the command returns the ID of the existing entry instead of creating a duplicate.

The producer-id identifies the source of the message, while the idempotent-id ensures uniqueness within that producer-id's message stream. Redis maintains an internal map of recent producer-id/idempotent-id combinations to detect and prevent duplicates.

Both modes can only be specified when the entry ID is * (auto-generated).

Use XCFGSET to configure how long idempotent IDs are retained (IDMP-DURATION) and the maximum number tracked per producer (IDMP-MAXSIZE).

See Idempotent message processing for more information.

KEEPREF | DELREF | ACKED

Specifies how to handle consumer group references when trimming. If there are no consumer groups, these arguments have no effect. 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 | MINID

The trimming strategy:

  • MAXLEN: Evicts entries as long as the stream's length exceeds the specified threshold
  • MINID: Evicts entries with IDs lower than the specified threshold (available since Redis 6.2.0)
= | ~

The trimming operator:

  • =: Exact trimming (default) - trims to the exact threshold
  • ~: Approximate trimming - more efficient, may leave slightly more entries than the threshold
threshold

The trimming threshold:

  • For MAXLEN: threshold is a non-negative integer specifying the maximum number of entries that may remain in the stream after trimming. Redis enforces this by removing the oldest entries - that is, the entries with the lowest stream IDs - so that only the newest entries are kept.
  • For MINID: threshold is a stream ID. All entries whose IDs are less than threshold are trimmed. All entries with IDs greater than or equal to threshold are kept.
LIMIT count

Limits the number of entries to examine during trimming. Available since Redis 6.2.0. When not specified, Redis uses a default value of 100 * the number of entries in a macro node. Specifying 0 disables the limiting mechanism entirely.

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.

Note:
XADD is the only Redis command that can add data to a stream. However, other commands, such as XDEL and XTRIM, can remove data from a stream.

Specifying a Stream ID as an argument

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.

Capped streams

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.

Additional information about streams

For more information about Redis streams, see the introduction to Redis Streams document.

Examples

XADD mystream * name Sara surname OConnor XADD mystream * field1 value1 field2 value2 field3 value3 XLEN mystream XRANGE mystream - +

Idempotent message processing examples

XADD mystream IDMP producer1 msg1 * field value XADD mystream IDMP producer1 msg1 * field different_value XADD mystream IDMPAUTO producer2 * field value XADD mystream IDMPAUTO producer2 * field value XCFGSET mystream IDMP-DURATION 300 IDMP-MAXSIZE 1000

Redis Software and Redis Cloud compatibility

Redis
Software		 Redis
Cloud		 Notes
✅ Standard
✅ Active-Active		 ✅ Standard
✅ Active-Active

Return information

One of the following:

  • Bulk string reply: The ID of the added entry. The ID is the one automatically generated if an asterisk (*) is passed as the id argument, otherwise the command just returns the same ID specified by the user during insertion. When using IDMP and a duplicate is detected, returns the ID of the existing entry.
  • Nil reply: if the NOMKSTREAM option is given and the key doesn't exist.

History

  • Starting with Redis version 6.2.0: Added the NOMKSTREAM option, MINID trimming strategy and the LIMIT option.
  • Starting with Redis version 7.0.0: Added support for the <ms>-* explicit ID form.
RATE THIS PAGE
Back to top ↑