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
Copy file name to clipboardExpand all lines: content/commands/xautoclaim.md
+57-12Lines changed: 57 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,22 +79,22 @@ title: XAUTOCLAIM
79
79
This command transfers ownership of pending stream entries that match the specified criteria. Conceptually, `XAUTOCLAIM` is equivalent to calling [`XPENDING`]({{< relref "/commands/xpending" >}}) and then [`XCLAIM`]({{< relref "/commands/xclaim" >}}),
80
80
but provides a more straightforward way to deal with message delivery failures via [`SCAN`]({{< relref "/commands/scan" >}})-like semantics.
81
81
82
-
Like [`XCLAIM`]({{< relref "/commands/xclaim" >}}), the command operates on the stream entries at `<key>` and in the context of the provided `<group>`.
83
-
It transfers ownership to `<consumer>` of messages pending for more than `<min-idle-time>` milliseconds and having an equal or greater ID than `<start>`.
82
+
Like [`XCLAIM`]({{< relref "/commands/xclaim" >}}), the command operates on the stream entries at `key` and in the context of the provided `group`.
83
+
It transfers ownership to `consumer` of messages pending for more than `min-idle-time` milliseconds and having an equal or greater ID than `start`.
84
84
85
-
The optional `<count>` argument, which defaults to 100, is the upper limit of the number of entries that the command attempts to claim.
86
-
Internally, the command begins scanning the consumer group's Pending Entries List (PEL) from `<start>` and filters out entries having an idle time less than or equal to `<min-idle-time>`.
87
-
The maximum number of pending entries that the command scans is the product of multiplying `<count>`'s value by 10 (hard-coded).
85
+
The optional `count` argument, which defaults to 100, is the upper limit of the number of entries that the command attempts to claim.
86
+
Internally, the command begins scanning the consumer group's Pending Entries List (PEL) from `start` and filters out entries having an idle time less than or equal to `min-idle-time`.
87
+
The maximum number of pending entries that the command scans is the product of multiplying `count`'s value by 10 (hard-coded).
88
88
It is possible, therefore, that the number of entries claimed will be less than the specified value.
89
89
90
90
The optional `JUSTID` argument changes the reply to return just an array of IDs of messages successfully claimed, without returning the actual message.
91
91
Using this option means the retry counter is not incremented.
92
92
93
-
The command returns the claimed entries as an array. It also returns a stream ID intended for cursor-like use as the `<start>` argument for its subsequent call.
93
+
The command returns the claimed entries as an array. It also returns a stream ID intended for cursor-like use as the `start` argument for its subsequent call.
94
94
When there are no remaining PEL entries, the command returns the special `0-0` ID to signal completion.
95
-
However, note that you may want to continue calling `XAUTOCLAIM` even after the scan is complete with the `0-0` as `<start>` ID, because enough time passed, so older pending entries may now be eligible for claiming.
95
+
However, note that you may want to continue calling `XAUTOCLAIM` even after the scan is complete with the `0-0` as `start` ID, because enough time passed, so older pending entries may now be eligible for claiming.
96
96
97
-
Note that only messages that are idle longer than `<min-idle-time>` are claimed, and claiming a message resets its idle time.
97
+
Note that only messages that are idle longer than `min-idle-time` are claimed, and claiming a message resets its idle time.
98
98
This ensures that only a single consumer can successfully claim a given pending message at a specific instant of time and trivially reduces the probability of processing the same message multiple times.
99
99
100
100
Messages that have been released back to the group using [`XNACK`]({{< relref "/commands/xnack" >}}) are immediately claimable since their delivery time is set to 0, satisfying any minimum idle time requirement.
@@ -105,6 +105,52 @@ These message IDs are returned to the caller as a part of `XAUTOCLAIM`s reply.
105
105
Lastly, claiming a message with `XAUTOCLAIM` also increments the attempted deliveries count for that message, unless the `JUSTID` option has been specified (which only delivers the message ID, not the message itself).
106
106
Messages that cannot be processed for some reason - for example, because consumers systematically crash when processing them - will exhibit high attempted delivery counts that can be detected by monitoring.
Return only the IDs of the claimed messages, without their fields, and do not increment their retry counters.
151
+
152
+
</details>
153
+
108
154
## Examples
109
155
110
156
```
@@ -116,10 +162,9 @@ Messages that cannot be processed for some reason - for example, because consume
116
162
3) (empty array)
117
163
```
118
164
119
-
In the above example, we attempt to claim up to 25 entries that are pending and idle (not having been acknowledged or claimed) for at least an hour, starting at the stream's beginning.
120
-
The consumer "Alice" from the "mygroup" group acquires ownership of these messages.
121
-
Note that the stream ID returned in the example is `0-0`, indicating that the entire stream was scanned.
122
-
We can also see that `XAUTOCLAIM` did not stumble upon any deleted messages (the third reply element is an empty array).
165
+
In the previous example, you claim up to 25 pending entries that have been idle (having not been acknowledged or claimed) for at least one hour, starting from the beginning of the stream. The consumer Alice in the mygroup group takes ownership of these messages.
166
+
167
+
The returned stream ID is 0-0, which indicates that XAUTOCLAIM scanned the entire stream. The third reply element is an empty array, which means XAUTOCLAIM did not find any deleted messages.
Copy file name to clipboardExpand all lines: content/commands/xclaim.md
+70-11Lines changed: 70 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,18 +121,77 @@ Moreover, as a side effect, `XCLAIM` will increment the count of attempted deliv
121
121
In both cases the reply will not contain a corresponding entry to that message (i.e. the length of the reply array may be smaller than the number of IDs provided to `XCLAIM`).
122
122
In the latter case, the message will also be deleted from the PEL in which it was found. This feature was introduced in Redis 7.0.
123
123
124
-
## Command options
124
+
## Required arguments
125
125
126
-
The command has multiple options, however most are mainly for internal use in
127
-
order to transfer the effects of `XCLAIM` or other commands to the AOF file
128
-
and to propagate the same effects to the replicas, and are unlikely to be
129
-
useful to normal users:
126
+
<detailsopen><summary><code>key</code></summary>
130
127
131
-
1.`IDLE <ms>`: Set the idle time (last time it was delivered) of the message. If IDLE is not specified, an IDLE of 0 is assumed, that is, the time count is reset because the message has now a new owner trying to process it.
132
-
2.`TIME <ms-unix-time>`: This is the same as IDLE but instead of a relative amount of milliseconds, it sets the idle time to a specific Unix time (in milliseconds). This is useful in order to rewrite the AOF file generating `XCLAIM` commands.
133
-
3.`RETRYCOUNT <count>`: Set the retry counter to the specified value. If not set, `XCLAIM` will increment the retry counter every time a message is delivered again.
134
-
4.`FORCE`: Creates the pending message entry in the PEL even if certain specified IDs are not already in the PEL assigned to a different client. However the message must be exist in the stream, otherwise the IDs of non existing messages are ignored.
135
-
5.`JUSTID`: Return just an array of IDs of messages successfully claimed, without returning the actual message. Using this option means the retry counter is not incremented.
Most of the following options are mainly for internal use, to transfer the effects of `XCLAIM` to the AOF file and replicas, and are unlikely to be useful to normal users.
Set the idle time (last time it was delivered) of the message. If `IDLE` is not specified, an idle time of `0` is assumed, that is, the time count is reset because the message now has a new owner trying to process it.
The same as `IDLE` but sets the idle time to a specific Unix time (in milliseconds) instead of a relative amount of milliseconds. This is useful in order to rewrite the AOF file generating `XCLAIM` commands.
Create the pending message entry in the PEL even if the specified IDs are not already in the PEL assigned to a different client. However, the message must exist in the stream, otherwise the IDs of non-existing messages are ignored.
Return just an array of IDs of messages successfully claimed, without returning the actual messages. Using this option means the retry counter is not incremented.
Update the consumer group's last-delivered ID to the given ID.
193
+
194
+
</details>
136
195
137
196
## Examples
138
197
@@ -143,7 +202,7 @@ useful to normal users:
143
202
2) "orange"
144
203
```
145
204
146
-
In the above example we claim the message with ID `1526569498055-0`, only if the message is idle for at least one hour without the original consumer or some other consumer making progresses (acknowledging or claiming it), and assigns the ownership to the consumer `Alice`.
205
+
In the previous example, you claim the message with ID 1526569498055-0 and assign it to the consumer Alice, but only if neither the original consumer nor another consumer has acknowledged or claimed it for at least one hour.
Copy file name to clipboardExpand all lines: content/commands/xgroup-create.md
+37-3Lines changed: 37 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -72,20 +72,20 @@ summary: Creates a consumer group.
72
72
syntax_fmt: "XGROUP CREATE key group <id | $> [MKSTREAM]\n [ENTRIESREAD\_entries-read]"
73
73
title: XGROUP CREATE
74
74
---
75
-
Create a new consumer group uniquely identified by `<groupname>` for the stream stored at `<key>`
75
+
Create a new consumer group uniquely identified by `groupname` for the stream stored at `key`
76
76
77
77
Every group has a unique name in a given stream.
78
78
When a consumer group with the same name already exists, the command returns a `-BUSYGROUP` error.
79
79
80
-
The command's `<id>` argument specifies the last delivered entry in the stream from the new group's perspective.
80
+
The command's `id` argument specifies the last delivered entry in the stream from the new group's perspective.
81
81
The special ID `$` is the ID of the last entry in the stream, but you can substitute it with any valid ID.
82
82
83
83
For example, if you want the group's consumers to fetch the entire stream from the beginning, use zero as the starting ID for the consumer group:
84
84
85
85
XGROUP CREATE mystream mygroup 0
86
86
87
87
By default, the `XGROUP CREATE` command expects that the target stream exists, and returns an error when it doesn't.
88
-
If a stream does not exist, you can create it automatically with length of 0 by using the optional `MKSTREAM` subcommand as the last argument after the `<id>`:
88
+
If a stream does not exist, you can create it automatically with length of 0 by using the optional `MKSTREAM` subcommand as the last argument after the `id`:
89
89
90
90
XGROUP CREATE mystream mygroup $ MKSTREAM
91
91
@@ -94,6 +94,40 @@ An arbitrary ID is any ID that isn't the ID of the stream's first entry, last en
94
94
Use it to find out how many entries are between the arbitrary ID (excluding it) and the stream's last entry.
95
95
Set the `entries_read` the stream's `entries_added` subtracted by the number of entries.
The ID of the last delivered message the group starts reading after. Use `$` for the last message currently in the stream, or `0` to read from the start.
0 commit comments