xgroup-create.3valkey - Man Page

XGROUP CREATE key group <id | $> [MKSTREAM] [ENTRIESREAD entries-read]

Create a new consumer group uniquely identified by <groupname> for the stream stored at <key>

Every group has a unique name in a given stream. When a consumer group with the same name already exists, the command returns a -BUSYGROUP error.

The command’s <id> argument specifies the last delivered entry in the stream from the new group’s perspective. The special ID $ is the ID of the last entry in the stream, but you can substitute it with any valid ID.

For example, if you want the group’s consumers to fetch the entire stream from the beginning, use zero as the starting ID for the consumer group:

XGROUP CREATE mystream mygroup 0

By default, the XGROUP CREATE command expects that the target stream exists, and returns an error when it doesn’t. If a stream does not exist, you can create it automatically with length of 0 by using the optional MKSTREAM subcommand as the last argument after the <id>:

XGROUP CREATE mystream mygroup $ MKSTREAM

To enable consumer group lag tracking, specify the optional entries_read named argument with an arbitrary ID. An arbitrary ID is any ID that isn’t the ID of the stream’s first entry, last entry, or zero (“0-0”) ID. Use it to find out how many entries are between the arbitrary ID (excluding it) and the stream’s last entry. Set the entries_read the stream’s entries_added subtracted by the number of entries.

valkey-protocol(7) Simple string reply: OK.

O(1)

@slow @stream @write

• Available since: 5.0.0
• Changed in 7.0.0: Added the entries_read named argument.

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