XCLAIM(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 XCLAIM — the "hey bestie, that message is mine now" command

okay so this is from the Valkey Command Manual, and it's about XCLAIM (the (3valkey) vibe, iykyk). Buckle up.

✨ NAME ✨

xclaim — changes, or acquires, ownership of a message in a consumer group, as if the message was delivered to a consumer group member. it's giving handover era. 👑

🎀 SYNOPSIS 🎀

XCLAIM key group consumer min-idle-time ID [ID...]  [IDLE ms] [TIME
unix-time-milliseconds] [RETRYCOUNT count] [FORCE] [JUSTID] [LASTID
lastid]

yes there are so many brackets. no we are not scared of them. 🫶

🦋 DESCRIPTION 🦋

okay so picture this: you're in a stream consumer group, and this command literally changes the ownership of a pending message so the new owner is the consumer you passed as the command argument. the way that works is wild, let me walk you through it:

  1. There is a stream with an associated consumer group.
  2. Some consumer A reads a message via XREADGROUP from a stream, in the context of that consumer group.
  3. As a side effect a pending message entry is created in the Pending Entries List (PEL) of the consumer group: it means the message was delivered to a given consumer, but it was not yet acknowledged via XACK.
  4. Then suddenly that consumer fails forever. 💀 (rip bestie, no cap)
  5. Other consumers may inspect the list of pending messages, that are stale for quite some time, using the 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 valkey-streams-intro(7) Stream intro documentation. read it, it eats.

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). so like, no double-dipping, but also double-dipping happens, it's a whole thing. 😭

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. the counter is literally the snitch. 🙈

XCLAIM will not claim a message in the following cases:

  1. The message doesn't exist in the group PEL (i.e. it was never read by any consumer)
  2. The message exists in the group PEL but not in the stream itself (i.e. the message was read but never acknowledged, and then was deleted from the stream, either by trimming or by 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. ghosted by your own PEL, honestly iconic. 🧚

🌸 Command options 🌸

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. (translation: these are dev-zone options, you probably don't need them, but we're listing all of them because details are sacred.)

  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.
  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.
  3. 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.
  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. FORCE is FORCE, bestie. 💅
  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.

⭐ REPLY ⭐

Any of the following:

  • valkey-protocol(7) Array reply: when the JUSTID option is specified, an array of IDs of messages successfully claimed.
  • valkey-protocol(7) Array reply: an array of stream entries, each of which contains an array of two elements, the entry ID and the entry data itself.

🔥 COMPLEXITY 🔥

O(log N) with N being the number of messages in the PEL of the consumer group. logarithmic, we love to see it.

💜 ACL CATEGORIES 💜

@fast @stream @write

🌈 HISTORY 🌈

  • Available since: 5.0.0

🍓 EXAMPLES 🍓

> 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. go Alice, go Alice. 👑

👑 SEE ALSO 👑

xack(3valkey), xadd(3valkey), xautoclaim(3valkey), xdel(3valkey), xgroup(3valkey), xgroup-create(3valkey), xgroup-createconsumer(3valkey), xgroup-delconsumer(3valkey), xgroup-destroy(3valkey), xgroup-help(3valkey), xgroup-setid(3valkey), xinfo(3valkey), xinfo-consumers(3valkey), xinfo-groups(3valkey), xinfo-help(3valkey), xinfo-stream(3valkey), xlen(3valkey), xpending(3valkey), xrange(3valkey), xread(3valkey), xreadgroup(3valkey), xrevrange(3valkey), xsetid(3valkey), xtrim(3valkey)

okay that's the whole thing, you read it all, I'm so proud of you. this was XCLAIM(3valkey) from version 9.0.0, dated 2025-10-21. go claim your messages, bestie, and don't forget to XACK. 💖✨🦋

📦 where this page comes from