You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Acknowledges and conditionally deletes one or multiple entries (messages) for a stream consumer group at the specified `key`.
83
+
84
+
`XACKDEL` combines the functionality of [`XACK`]({{< relref "/commands/xack" >}}) and [`XDEL`]({{< relref "/commands/xdel" >}}) in Redis Streams. It acknowledges the specified entry IDs in the given consumer group and simultaneously attempts to delete the corresponding entries from the stream.
85
+
86
+
## Required arguments
87
+
88
+
<detailsopen>
89
+
<summary><code>key</code></summary>
90
+
91
+
The name of the stream key.
92
+
</details>
93
+
94
+
<detailsopen>
95
+
<summary><code>group</code></summary>
96
+
97
+
The name of the consumer group.
98
+
</details>
99
+
100
+
<detailsopen>
101
+
<summary><code>IDS numids id [id ...]</code></summary>
102
+
103
+
The IDS block specifying which entries to acknowledge and delete:
104
+
-`numids`: The number of IDs that follow
105
+
-`id [id ...]`: One or more stream entry IDs to acknowledge and delete
Specifies how to handle consumer group references when acknowledging and deleting entries. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default:
114
+
115
+
-`KEEPREF` (default): Acknowledges the entries 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).
116
+
-`DELREF`: Acknowledges the entries 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 entries. If an entry ID is not in the stream, but there are dangling references, `XACKDEL` with `DELREF` would still remove all those references.
117
+
-`ACKED`: Acknowledges the entries in the specified consumer group and only deletes entries that were read and acknowledged by all consumer groups.
118
+
</details>
119
+
120
+
This command is particularly useful when you want to both acknowledge entry processing and clean up the stream in a single atomic operation, providing fine-grained control over how entry references are handled.
121
+
122
+
{{< note >}}
123
+
When using multiple consumer groups, users are encouraged to use `XACKDEL` with the `ACKED` option instead of `XACK` and `XDEL`, simplifying the application logic.
124
+
{{< /note >}}
125
+
126
+
## Examples
127
+
128
+
{{% redis-cli %}}
129
+
XADD mystream * field1 value1
130
+
XADD mystream * field2 value2
131
+
XGROUP CREATE mystream mygroup 0
132
+
XREADGROUP GROUP mygroup consumer1 COUNT 2 STREAMS mystream >
*[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
148
+
*[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID:
149
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream.
150
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key.
151
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
152
+
153
+
-tab-sep-
154
+
155
+
One of the following:
156
+
157
+
*[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
158
+
*[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID:
159
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream.
160
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key.
161
+
*[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
\ [LIMIT\_count]] <* | id> field value [field value ...]"
122
140
title: XADD
123
141
---
124
-
Appends the specified stream entry to the stream at the specified key.
125
-
If the key does not exist, as a side effect of running this command the
126
-
key is created with a stream value. The creation of stream's key can be
127
-
disabled with the `NOMKSTREAM` option.
128
142
129
-
An entry is composed of a list of field-value pairs.
130
-
The field-value pairs are stored in the same order they are given by the user.
131
-
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`.
143
+
Appends the specified stream entry to the stream at the specified `key`.
144
+
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.
145
+
You can turn off key creation with the `NOMKSTREAM` option.
146
+
147
+
## Required arguments
148
+
149
+
<detailsopen>
150
+
<summary><code>key</code></summary>
151
+
152
+
The name of the stream key.
153
+
</details>
154
+
155
+
<detailsopen>
156
+
<summary><code>id</code></summary>
157
+
158
+
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`).
159
+
</details>
160
+
161
+
<detailsopen>
162
+
<summary><code>field value [field value ...]</code></summary>
132
163
133
-
`XADD` is the *only Redis command* that can add data to a stream, but
134
-
there are other commands, such as [`XDEL`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), that are able to
164
+
One or more field-value pairs that make up the stream entry. You must provide at least one field-value pair.
165
+
</details>
166
+
167
+
## Optional arguments
168
+
169
+
<detailsopen>
170
+
<summary><code>NOMKSTREAM</code></summary>
171
+
172
+
Prevents the creation of a new stream if the key does not exist. Available since Redis 6.2.0.
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:
179
+
180
+
-`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).
181
+
-`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.
182
+
-`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.
Trims the stream to maintain a specific size or remove old entries:
189
+
-`MAXLEN`: Limits the stream to a maximum number of entries
190
+
-`MINID`: Removes entries with IDs lower than the specified threshold (available since Redis 6.2.0)
191
+
-`=`: Exact trimming (default)
192
+
-`~`: Approximate trimming (more efficient)
193
+
-`threshold`: The maximum number of entries (for MAXLEN) or minimum ID (for MINID)
194
+
-`LIMIT count`: Limits the number of entries to examine during trimming (available since Redis 6.2.0)
195
+
</details>
196
+
197
+
Each entry consists of a list of field-value pairs.
198
+
Redis stores the field-value pairs in the same order you provide them.
199
+
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`.
200
+
201
+
{{< note >}}
202
+
`XADD` is the only Redis command that can add data to a stream. However,
203
+
other commands, such as [`XDEL`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), can
135
204
remove data from a stream.
205
+
{{< /note >}}
136
206
137
207
## Specifying a Stream ID as an argument
138
208
139
-
A stream entry ID identifies a given entry inside a stream.
209
+
A stream entry ID identifies a specific entry inside a stream.
140
210
141
-
The `XADD` command will auto-generate a unique ID for you if the ID argument
142
-
specified is the `*` character (asterisk ASCII character). However, while
143
-
useful only in very rare cases, it is possible to specify a well-formed ID, so
144
-
that the new entry will be added exactly with the specified ID.
211
+
`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.
145
212
146
-
IDs are specified by two numbers separated by a `-` character:
213
+
Specify IDs using two numbers separated by a `-` character:
147
214
148
215
1526919030474-55
149
216
150
-
Both quantities are 64-bit numbers. When an ID is auto-generated, the
217
+
Both numbers are 64-bit integers. When Redis auto-generates an ID, the
151
218
first part is the Unix time in milliseconds of the Redis instance generating
152
-
the ID. The second part is just a sequence number and is used in order to
219
+
the ID. The second part is a sequence number used to
153
220
distinguish IDs generated in the same millisecond.
154
221
155
-
You can also specify an incomplete ID, that consists only of the milliseconds part, which is interpreted as a zero value for sequence part.
222
+
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.
156
223
To have only the sequence part automatically generated, specify the milliseconds part followed by the `-` separator and the `*` character:
157
224
158
225
```
@@ -162,37 +229,25 @@ To have only the sequence part automatically generated, specify the milliseconds
162
229
"1526919030474-56"
163
230
```
164
231
165
-
IDs are guaranteed to be always incremental: If you compare the ID of the
166
-
entry just inserted it will be greater than any other past ID, so entries
167
-
are totally ordered inside a stream. In order to guarantee this property,
168
-
if the current top ID in the stream has a time greater than the current
169
-
local time of the instance, the top entry time will be used instead, and
170
-
the sequence part of the ID incremented. This may happen when, for instance,
171
-
the local clock jumps backward, or if after a failover the new master has
172
-
a different absolute time.
173
-
174
-
When a user specified an explicit ID to `XADD`, the minimum valid ID is
175
-
`0-1`, and the user *must* specify an ID which is greater than any other
176
-
ID currently inside the stream, otherwise the command will fail and return an error. Usually
177
-
resorting to specific IDs is useful only if you have another system generating
178
-
unique IDs (for instance an SQL table) and you really want the Redis stream
179
-
IDs to match the one of this other system.
232
+
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.
233
+
234
+
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.
180
235
181
236
## Capped streams
182
237
183
238
`XADD` incorporates the same semantics as the [`XTRIM`]({{< relref "/commands/xtrim" >}}) command - refer to its documentation page for more information.
184
-
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.
185
-
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).
239
+
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.
240
+
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).
186
241
187
242
For example, calling `XADD` in the following form:
0 commit comments