Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

XAUTOCLAIM

Last updated 
XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]
Group
Stream
Complexity
O(1) per entry looked at (at most 10 times COUNT)
Arity
-6 (at least 6 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

XAUTOCLAIM walks the pending entries list of the consumer group group from start, and gives every entry idle for at least min-idle-time milliseconds to consumer. It works like XPENDING followed by XCLAIM, and returns a cursor so you can continue the scan.

Claimed entries get their idle time reset and, without JUSTID, their delivery count raised by one. Pending entries that were deleted from the stream are removed from the pending list and reported separately. The consumer is created if it does not exist.

Arguments and options

Section titled “Arguments and options”
Argument Effect
start Where the scan starts: an ID, - for the first pending entry, or ( before an ID to start after it. Use 0-0 to start from the beginning.
COUNT count Claim at most count entries (default 100). One call looks at no more than 10 times count pending entries.
JUSTID Return IDs only, and leave delivery counts unchanged.

Return value

Section titled “Return value”

An array of three elements, the same in RESP2 and RESP3:

Element Value
1 Bulk string: the ID to pass as start next time, 0-0 when the scan reached the end
2 Array of claimed entries, each [id, [field, value, ...]] (IDs only with JUSTID)
3 Array of IDs that were pending but no longer exist in the stream

Error replies:

  • NOGROUP No such key 'key' or consumer group 'group' when the stream or the group does not exist.
  • ERR Invalid min-idle-time argument for XAUTOCLAIM
  • ERR COUNT must be > 0
  • ERR Invalid stream ID specified as stream command argument, ERR invalid start ID for the interval, ERR syntax error, or WRONGTYPE.

Examples

Section titled “Examples”
127.0.0.1:6379> XADD tasks 1700000000000-0 job email
"1700000000000-0"
127.0.0.1:6379> XADD tasks 1700000000001-0 job sms
"1700000000001-0"
127.0.0.1:6379> XGROUP CREATE tasks workers 0
OK
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
      2) 1) "1700000000001-0"
         2) 1) "job"
            2) "sms"
127.0.0.1:6379> XDEL tasks 1700000000001-0
(integer) 1
127.0.0.1:6379> XAUTOCLAIM tasks workers bob 0 0-0 COUNT 10
1) "0-0"
2) 1) 1) "1700000000000-0"
      2) 1) "job"
         2) "email"
3) 1) "1700000000001-0"

Compatibility

Section titled “Compatibility”

Same as Redis 7 and Valkey 8, including the third reply element with deleted IDs.

See also

Section titled “See also”

XCLAIM, XPENDING, XACK, XREADGROUP