Skip to content

DOC-5366: write new streams docs for ROS8.2 #1788

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 3, 2025
Merged

DOC-5366: write new streams docs for ROS8.2 #1788

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9af5f36
DEV: write new streams docs for ROS8.2
dwdougherty Jul 1, 2025
0ad2bfd
Apply suggestions from code review
dwdougherty Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 153 additions & 0 deletions content/commands/xackdel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
---
acl_categories:
- '@write'
- '@stream'
- '@fast'
arguments:
- display_text: key
key_spec_index: 0
name: key
type: key
- display_text: group
name: group
type: string
- arguments:
- display_text: keepref
name: keepref
token: KEEPREF
type: pure-token
- display_text: delref
name: delref
token: DELREF
type: pure-token
- display_text: acked
name: acked
token: ACKED
type: pure-token
name: condition
optional: true
type: oneof
- arguments:
- display_text: numids
name: numids
type: integer
- display_text: id
multiple: true
name: id
type: string
name: ids
token: IDS
type: block
arity: -6
categories:
- docs
- develop
- stack
- oss
- rs
- rc
- oss
- kubernetes
- clients
command_flags:
- write
- fast
complexity: O(1) for each message ID processed.
description: Acknowledges and deletes one or multiple messages for a stream consumer
group.
group: stream
hidden: false
key_specs:
- RW: true
begin_search:
spec:
index: 1
type: index
delete: true
find_keys:
spec:
keystep: 1
lastkey: 0
limit: 0
type: range
update: true
linkTitle: XACKDEL
since: 8.2.0
summary: Acknowledges and deletes one or multiple messages for a stream consumer group.
syntax_fmt: "XACKDEL key group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]"
syntax_str: "group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]"
title: XACKDEL
---

Acknowledges and deletes one or multiple messages for a stream consumer group at the specified `key`.

`XACKDEL` combines the functionality of [`XACK`]({{< relref "/commands/xack" >}}) and [`XDEL`]({{< relref "/commands/xdel" >}}) in Redis Streams. It acknowledges the specified message IDs in the given consumer group and simultaneously attempts to delete the corresponding entries from the stream.

## Required arguments

<details open>
<summary><code>key</code></summary>

The name of the stream key.
</details>

<details open>
<summary><code>group</code></summary>

The name of the consumer group.
</details>

<details open>
<summary><code>IDS numids id [id ...]</code></summary>

The IDS block specifying which entries to acknowledge and delete:
- `numids`: The number of IDs that follow
- `id [id ...]`: One or more stream entry IDs to acknowledge and delete
</details>

## Optional arguments

<details open>
<summary><code>KEEPREF | DELREF | ACKED</code></summary>

Specifies how to handle consumer group references when acknowledging and deleting entries. Available since Redis 8.2.0. If no option is specified, `KEEPREF` is used by default:

- `KEEPREF` (default): Acknowledges the messages in the specified consumer group and deletes the entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).
- `DELREF`: Acknowledges the messages in the specified consumer group, deletes the entries from the stream, and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages.
- `ACKED`: Acknowledges the messages in the specified consumer group and only deletes entries that were read and acknowledged by all consumer groups.
</details>

This command is particularly useful when you want to both acknowledge message processing and clean up the stream in a single atomic operation, providing fine-grained control over how consumer group references are handled.

## Examples

{{% redis-cli %}}
XADD mystream * field1 value1
XADD mystream * field2 value2
XGROUP CREATE mystream mygroup 0
XREADGROUP GROUP mygroup consumer1 COUNT 2 STREAMS mystream >
XPENDING mystream mygroup
XACKDEL mystream mygroup KEEPREF IDS 2 1526919030474-55 1526919030474-56
XPENDING mystream mygroup
XRANGE mystream - +
{{% /redis-cli %}}

## Return information

{{< multitabs id="xackdel-return-info"
tab1="RESP2"
tab2="RESP3" >}}

[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was acknowledged and deleted from the stream.
* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).

-tab-sep-

[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was acknowledged and deleted from the stream.
* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).

{{< /multitabs >}}
139 changes: 97 additions & 42 deletions content/commands/xadd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,22 @@ arguments:
since: 6.2.0
token: NOMKSTREAM
type: pure-token
- arguments:
- display_text: keepref
name: keepref
token: KEEPREF
type: pure-token
- display_text: delref
name: delref
token: DELREF
type: pure-token
- display_text: acked
name: acked
token: ACKED
type: pure-token
name: condition
optional: true
type: oneof
- arguments:
- arguments:
- display_text: maxlen
Expand Down Expand Up @@ -98,6 +114,8 @@ history:
- Added the `NOMKSTREAM` option, `MINID` trimming strategy and the `LIMIT` option.
- - 7.0.0
- Added support for the `<ms>-*` explicit ID form.
- - 8.2.0
- Added the `KEEPREF`, `DELREF` and `ACKED` options.
key_specs:
- RW: true
begin_search:
Expand All @@ -115,44 +133,93 @@ key_specs:
linkTitle: XADD
since: 5.0.0
summary: Appends a new message to a stream. Creates the key if it doesn't exist.
syntax_fmt: "XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold\n [LIMIT\_\
count]] <* | id> field value [field value ...]"
syntax_str: "[NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]] <* |\
\ id> field value [field value ...]"
syntax_fmt: "XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID>\n\
\ [= | ~] threshold [LIMIT\_count]] <* | id> field value [field value\n ...]"
syntax_str: "[NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID> [= | ~] threshold\
\ [LIMIT\_count]] <* | id> field value [field value ...]"
title: XADD
---
Appends the specified stream entry to the stream at the specified key.
If the key does not exist, as a side effect of running this command the
key is created with a stream value. The creation of stream's key can be
disabled with the `NOMKSTREAM` option.

An entry is composed of a list of field-value pairs.
The field-value pairs are stored in the same order they are given by the user.
Commands that read the stream, such as [`XRANGE`]({{< relref "/commands/xrange" >}}) or [`XREAD`]({{< relref "/commands/xread" >}}), are guaranteed to return the fields and values exactly in the same order they were added by `XADD`.
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

<details open>
<summary><code>key</code></summary>

The name of the stream key.
</details>

<details open>
<summary><code>id</code></summary>

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`).
</details>

<details open>
<summary><code>field value [field value ...]</code></summary>

`XADD` is the *only Redis command* that can add data to a stream, but
there are other commands, such as [`XDEL`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), that are able to
One or more field-value pairs that make up the stream entry. You must provide at least one field-value pair.
</details>

## Optional arguments

<details open>
<summary><code>NOMKSTREAM</code></summary>

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

<details open>
<summary><code>KEEPREF | DELREF | ACKED</code></summary>

Specifies how to handle consumer group references when trimming. Available since Redis 8.2.0. 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.
</details>

<details open>
<summary><code>MAXLEN | MINID [= | ~] threshold [LIMIT count]</code></summary>

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)
</details>

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`]({{< relref "/commands/xrange" >}}) or [`XREAD`]({{< relref "/commands/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`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), can
remove data from a stream.
{{< /note >}}

## Specifying a Stream ID as an argument

A stream entry ID identifies a given entry inside a stream.
A stream entry ID identifies a specific entry inside a stream.

The `XADD` command will auto-generate a unique ID for you if the ID argument
specified is the `*` character (asterisk ASCII character). However, while
useful only in very rare cases, it is possible to specify a well-formed ID, so
that the new entry will be added exactly with the specified ID.
`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.

IDs are specified by two numbers separated by a `-` character:
Specify IDs using two numbers separated by a `-` character:

1526919030474-55

Both quantities are 64-bit numbers. When an ID is auto-generated, the
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 just a sequence number and is used in order to
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 is interpreted as a zero value for sequence part.
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:

```
Expand All @@ -162,37 +229,25 @@ To have only the sequence part automatically generated, specify the milliseconds
"1526919030474-56"
```

IDs are guaranteed to be always incremental: If you compare the ID of the
entry just inserted it will be greater than any other past ID, so entries
are totally ordered inside a stream. In order to guarantee this property,
if the current top ID in the stream has a time greater than the current
local time of the instance, the top entry time will be used instead, and
the sequence part of the ID incremented. This may happen when, for instance,
the local clock jumps backward, or if after a failover the new master has
a different absolute time.

When a user specified an explicit ID to `XADD`, the minimum valid ID is
`0-1`, and the user *must* specify an ID which is greater than any other
ID currently inside the stream, otherwise the command will fail and return an error. Usually
resorting to specific IDs is useful only if you have another system generating
unique IDs (for instance an SQL table) and you really want the Redis stream
IDs to match the one of this other system.
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`]({{< relref "/commands/xtrim" >}}) command - refer to its documentation page for more information.
This allows adding new entries and keeping 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 stream with `XADD` using **almost exact** trimming (the `~` argument).
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 ...
Will add a new entry but will also evict old entries so that the stream will contain only 1000 entries, or at most a few tens more.

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 further information about Redis streams please check our
For more information about Redis streams, see the
[introduction to Redis Streams document]({{< relref "/develop/data-types/streams" >}}).

## Examples
Expand Down
Loading