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.

XCLAIM

Last updated 
XCLAIM key group consumer min-idle-time id [id ...] [IDLE ms] [TIME unix-time-milliseconds] [RETRYCOUNT count] [FORCE] [JUSTID] [LASTID lastid]
Group
Stream
Complexity
O(log N) per ID
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

XCLAIM moves pending entries of the consumer group group to consumer, for example when the consumer that received them has stopped. An entry is claimed only if it has been idle (not delivered or claimed) for at least min-idle-time milliseconds, which keeps two consumers from claiming the same entry at once.

A claimed entry’s idle time restarts and its delivery count goes up by one (not with JUSTID). The consumer is created if it does not exist.

IDs that are not pending are skipped, unless FORCE is given. A pending entry that was deleted from the stream is dropped from the pending list and not returned.

Options

Section titled “Options”

The options follow the last ID.

Option Effect
IDLE ms Set the entry’s idle time to ms instead of 0.
TIME unix-time-milliseconds Set the entry’s last delivery time to this Unix time.
RETRYCOUNT count Set the delivery count to count.
FORCE Also claim IDs that are not pending, if the entry still exists in the stream.
JUSTID Return only the IDs, and leave the delivery count unchanged.
LASTID lastid Raise the group’s last delivered ID to lastid (it is never lowered).

A time in the future or a negative IDLE or TIME counts as now; a negative RETRYCOUNT is ignored. If both IDLE and TIME are given, the later one wins.

Return value

Section titled “Return value”
Case RESP2 RESP3
Default Array of claimed entries, each [id, [field, value, ...]] Same
JUSTID Array of claimed IDs as bulk strings Same

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 XCLAIM
  • ERR Invalid IDLE option argument for XCLAIM (and the same for TIME and RETRYCOUNT).
  • ERR Unrecognized XCLAIM option 'name'
  • ERR Invalid stream ID specified as stream command argument for a bad LASTID, or WRONGTYPE.

Examples

Section titled “Examples”
127.0.0.1:6379> XADD tasks 1700000000000-0 job email
"1700000000000-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"
127.0.0.1:6379> XCLAIM tasks workers bob 3600000 1700000000000-0
(empty array)
127.0.0.1:6379> XCLAIM tasks workers bob 0 1700000000000-0
1) 1) "1700000000000-0"
   2) 1) "job"
      2) "email"
127.0.0.1:6379> XPENDING tasks workers - + 10
1) 1) "1700000000000-0"
   2) "bob"
   3) (integer) 3
   4) (integer) 2

The first claim returns nothing because the entry has not been idle for an hour yet.

Compatibility

Section titled “Compatibility”

Same as Redis 7 and Valkey 8.

See also

Section titled “See also”

XAUTOCLAIM, XPENDING, XACK, XREADGROUP