Changes, or acquires, ownership of a message in a consumer group, as if the message was delivered a consumer group member.
XCLAIM
key group
consumer min-idle-time ID [ID…]
[IDLE
ms]
[TIME
unix-time-milliseconds]
[RETRYCOUNT
count]
[FORCE
]
[JUSTID
]
[LASTID
lastid]
In the context of a stream consumer group, this command changes the ownership of a pending message, so that the new owner is the consumer specified as the command argument. Normally this is what happens:
XREADGROUP
from a
stream, in the context of that consumer group.XACK
.XPENDING
command. In
order to continue processing such messages, they use XCLAIM
to acquire the ownership of the message and continue. Consumers can also
use the XAUTOCLAIM
command to automatically scan and claim
stale pending messages.This dynamic is clearly explained in the Stream intro documentation.
Note that the message is claimed only if its idle time is greater
than the minimum idle time we specify when calling XCLAIM
.
Because as a side effect XCLAIM
will also reset the idle
time (since this is a new attempt at processing the message), two
consumers trying to claim a message at the same time will never both
succeed: only one will successfully claim the message. This avoids that
we process a given message multiple times in a trivial way (yet multiple
processing is possible and unavoidable in the general case).
Moreover, as a side effect, XCLAIM
will increment the
count of attempted deliveries of the message unless the
JUSTID
option has been specified (which only delivers the
message ID, not the message itself). In this way messages that cannot be
processed for some reason, for instance because the consumers crash
attempting to process them, will start to have a larger counter and can
be detected inside the system.
XCLAIM
will not claim a message in the following
cases:
XDEL
)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
). In the latter case, the
message will also be deleted from the PEL in which it was found.
The command has multiple options, however most are mainly for
internal use in order to transfer the effects of XCLAIM
or
other commands to the AOF file and to propagate the same effects to the
replicas, and are unlikely to be useful to normal users:
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.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.RETRYCOUNT <count>
: Set the retry counter to the
specified value. This counter is incremented every time a message is
delivered again. Normally XCLAIM
does not alter this
counter, which is just served to clients when the XPENDING command is
called: this way clients can detect anomalies, like messages that are
never processed for some reason after a big number of delivery
attempts.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.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.Any of the following:
Array reply: when the JUSTID option is specified, an array of IDs of messages successfully claimed.
Array reply: an array of stream entries, each of which contains an array of two elements, the entry ID and the entry data itself.
O(log N) with N being the number of messages in the PEL of the consumer group.
@fast @stream @write
> XCLAIM mystream mygroup Alice 3600000 1526569498055-0
1) 1) 1526569498055-0
2) 1) "message"
2) "orange"
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
.
XACK, XADD, XAUTOCLAIM, XDEL, XGROUP, XGROUP CREATE, XGROUP CREATECONSUMER, XGROUP DELCONSUMER, XGROUP DESTROY, XGROUP HELP, XGROUP SETID, XINFO, XINFO CONSUMERS, XINFO GROUPS, XINFO HELP, XINFO STREAM, XLEN, XPENDING, XRANGE, XREAD, XREADGROUP, XREVRANGE, XSETID, XTRIM.