Command Introduction
Stream commands are used for managing the writing, reading, and consumption of persistent message streams (append-only logs), serving as a stateful enhanced edition of Pub/Sub. This command family is suitable for scenarios that require message persistence and consumption acknowledgment, such as message queues, Event Sourcing, and log aggregation. Based on their features, the core commands can be categorized into the following four types:
Writing and Reading Messages
XADD: Appends a message to the end of a stream and returns a unique message ID (supports auto-generation * or explicit specification).
XREAD: Reads messages from one or more streams, supporting starting from a specified ID or from the head/tail of a stream.
XRANGE / XREVRANGE: Searches for messages sequentially or in reverse order within a specified ID range.
XLEN: returns the number of messages in a stream.
Consumer Group Management (Multi-Consumer Collaboration)
XGROUP CREATE / XGROUP DESTROY / XGROUP SETID / XGROUP CREATECONSUMER: Creates or terminates consumer groups, sets or resets consumption progress, and registers consumers.
XREADGROUP: Reads pending messages assigned to itself by a consumer within a consumer group.
XACK: Acknowledges that a message has been processed and removes it from the pending list.
XPENDING: Views detailed information about pending (unacknowledged) messages in a consumer group.
XCLAIM / XAUTOCLAIM (Redis 6.2+): Transfers timed-out and unacknowledged messages to other consumers for failover. XAUTOCLAIM supports automatic scanning and claiming.
Message and Stream Lifecycle Management
XDEL: deletes specified messages by message ID.
XTRIM: Trims stream length based on conditions (MAXLEN / MINID) and supports approximate trimming (~) to reduce performance overhead.
Metadata Query
XINFO: Views detailed metadata for streams (GROUPS / CONSUMERS / STREAM) or consumer groups.
Command Support Overview
Basic Commands: xinfo, xadd, xtrim, xdel, xrange, xrevrange, xlen, xread, xgroup, xreadgroup, xack, xclaim, xpending. These commands are supported only by the standard architecture and cluster architecture of Redis versions 5.0, 6.2, and 7.0, and Valkey versions 8.0 and 9.0.
xautoclaim command: This command is supported only by Redis versions 6.2 and 7.0, and Valkey versions 8.0 and 9.0.
Redis versions 4.0 and 2.8: do not support all Stream family commands.
Cross-Slot Restriction: In a cluster architecture, xread and xreadgroup do not support cross-slot operations.
Command Compatibility Matrix
The support status of Stream family commands across different versions and architectures is shown in the table below (✓ indicates supported, ✗ indicates not supported, and — indicates that the command does not involve a cross-slot access scenario).
|
xinfo | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xadd | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xtrim | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xdel | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xrange | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xrevrange | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xlen | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xread | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ |
xgroup | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xreadgroup | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ |
xack | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xclaim | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xpending | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | — |
xautoclaim | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | — |