XREADGROUP

XREADGROUP reads streams on behalf of consumer in the consumer group group. Each new entry goes to one consumer of the group only, and stays in the group’s pending entries list (PEL) under that consumer until it is acknowledged with XACK or claimed by another consumer.

The consumer is created on first use. The group must already exist (see XGROUP CREATE).

IDs

ID	Meaning
>	New entries that no consumer of the group has received yet. They are added to the PEL (unless NOACK) and move the group’s last delivered ID forward.
Any other ID (for example 0)	This consumer’s history: its pending entries with an ID greater than the given one. Nothing new is delivered.

Reading history counts as another delivery: each returned entry’s delivery count goes up by one and its idle time restarts. A pending entry that was deleted from the stream is returned as its ID with a nil body.

$ is not accepted.

Options

Option	Effect
COUNT count	At most count entries per stream (0 means no limit).
BLOCK milliseconds	With >, wait up to this long for new entries when there are none. 0 waits with no time limit. Ignored when reading history.
NOACK	Do not add the delivered entries to the PEL: they count as acknowledged at once.

If the stream or the group is deleted while a call is blocked, the call ends with the NOGROUP error.

Return value

Each entry is [id, [field, value, ...]].

Case	RESP2	RESP3
New entries (>)	Array of [key, entries] pairs, only streams with entries	Map of key to entries
History (other IDs)	Array of [key, entries] pairs for every stream named, even with no entries	Map of key to entries
No new entries, without BLOCK or after the timeout	Nil array	Null

Error replies:

• NOGROUP No such key 'key' or consumer group 'group' in XREADGROUP with GROUP option when the stream or the group does not exist.
• ERR The $ ID is meaningless in the context of XREADGROUP: ... for $.
• ERR Unbalanced 'xreadgroup' list of streams: for each stream key an ID or '>' must be specified.
• ERR value is not an integer or out of range for a negative or non-numeric COUNT.
• ERR Invalid stream ID specified as stream command argument, ERR syntax error, timeout errors as for XREAD, or WRONGTYPE.

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 COUNT 1 STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
127.0.0.1:6379> XREADGROUP GROUP workers bob STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000001-0"
         2) 1) "job"
            2) "sms"
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks 0
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
127.0.0.1:6379> XACK tasks workers 1700000000000-0
(integer) 1
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks 0
1) 1) "tasks"
   2) (empty array)

Compatibility

Same as Redis 7 and Valkey 8.

See also

XGROUP CREATE, XACK, XPENDING, XCLAIM, XAUTOCLAIM, XREAD