XAUTOCLAIM(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 XAUTOCLAIM 💖

okay bestie, sit down, hydrate, and let me tell you about xautoclaim — it's the 3valkey manual page that changes, or acquires, ownership of messages in a consumer group, as if the messages were delivered to as consumer group member. yes that's the whole NAME line, and yes it's iconic. 🎀

✨ SYNOPSIS ✨

XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]

that's the whole vibe. five things you must give her, two optional little accessories. 💅

🌸 DESCRIPTION 🌸

so this command transfers ownership of pending stream entries that match the specified criteria. conceptually — and this is the glow-up — XAUTOCLAIM is equivalent to calling XPENDING and then XCLAIM, except it's the more straightforward way to deal with message delivery failures, because it uses SCAN-like semantics. no cap. 🦋

like XCLAIM, the command operates on the stream entries at key and in the context of the provided group. it transfers ownership to consumer of messages pending for more than min-idle-time milliseconds and having an equal or greater ID than start. periodt. 👑

the optional count argument — which defaults to 100, bestie, remember that — is the upper limit of the number of entries that the command attempts to claim. 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. and here's the plot twist: the maximum number of pending entries that the command scans is the product of multiplying count's value by 10 (hard-coded). so it is possible, therefore, that the number of entries claimed will be less than the specified value. not a bug, just math. 😭

the optional JUSTID argument changes the reply to return just an array of IDs of messages successfully claimed, without returning the actual message. and listen — using this option means the retry counter is not incremented. so if you're tracking retries, that's a whole different situation. 🙈

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. when there are no remaining PEL entries, the command returns the special 0-0 ID to signal completion. however — and this is important — 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. she comes back around, okay? 🔥

note that only messages that are idle longer than min-idle-time are claimed, and claiming a message resets its idle time. 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. we love a mutual-exclusion moment. ✨

while iterating the PEL, if XAUTOCLAIM stumbles upon a message which doesn't exist in the stream anymore (either trimmed or deleted by XDEL) it does not claim it, and deletes it from the PEL in which it was found. these message IDs are returned to the caller as a part of XAUTOCLAIMs reply. she's cleaning up as she goes, we stan a tidy queen. 🧹

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). 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. that's your red flag radar, bestie. 💀

🎀 REPLY 🎀

valkey-protocol(7) Array reply, specifically, an array with three elements:

  1. A stream ID to be used as the start argument for the next call to XAUTOCLAIM.
  2. An valkey-protocol(7) Array reply containing all the successfully claimed messages in the same format as XRANGE.
  3. An valkey-protocol(7) Array reply containing message IDs that no longer exist in the stream, and were deleted from the PEL in which they were found.

three elements. trio. the holy trinity of claim, scan, and cleanup. 💜

👑 COMPLEXITY 👑

O(1) if COUNT is small.

tiny count, tiny cost. slay. 💅

🌈 ACL CATEGORIES 🌈

@fast @stream @write

🦋 HISTORY 🦋

  • Available since: 6.2.0
  • Changed in 7.0.0: Added an element to the reply array, containing deleted entries the command cleared from the PEL

glow-up confirmed. the third array element was the 7.0.0 era upgrade. ✨

⭐ EXAMPLES ⭐

> XAUTOCLAIM mystream mygroup Alice 3600000 0-0 COUNT 25
1) "0-0"
2) 1) 1) "1609338752495-0"
      2) 1) "field"
         2) "value"
3) (empty array)

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. the consumer "Alice" from the "mygroup" group acquires ownership of these messages. note that the stream ID returned in the example is 0-0, indicating that the entire stream was scanned. we can also see that XAUTOCLAIM did not stumble upon any deleted messages (the third reply element is an empty array). Alice ate and left no crumbs. 🍓

🫶 SEE ALSO 🫶

xack(3valkey), xadd(3valkey), xclaim(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)

💖 ok that's the whole page, bestie. go forth and claim your pending entries. no cap, you got this. 💖

this lil manual moment was brought to you by Valkey 9.0.0, dated 2025-10-21, filed under XAUTOCLAIM(3valkey) — mwah, bye!! 🎀✨🦋

📦 where this page comes from