XADD

Syntax
XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<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,

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.

KEEPREF | DELREF | ACKED

Specifies 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 entries
  • MINID: 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.

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

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.
  • 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.
  • Starting with Redis version 8.2.0: Added the KEEPREF, DELREF and ACKED options.