Stream Commands

XADD-&-XREAD

Redis Streams are append-only logs with consumer groups. Build event sourcing, message queues, and real-time pipelines with persistent, replayable data.

You'll Learn

  • Adding entries with XADD
  • Reading with XREAD and XRANGE
  • Consumer groups for distributed processing
  • Stream trimming and memory management
Free Download

See Your Data, Not Terminal Text

Redimo visualizes every Redis data type beautifully. Edit inline, undo mistakes, stay safe in production.

1. What Are Redis Streams?

Streams are Redis's answer to Kafka-style event logs. Each entry has a unique ID (timestamp-based), can contain multiple field-value pairs, and persists until explicitly deleted.

Unlike Pub/Sub (fire-and-forget) or Lists (simple queues), Streams support consumer groups, message acknowledgment, and replay from any point in history.

Key Concepts

Stream Entry ID: 1705312245123-0
                   └── timestamp ──┘ └─ sequence

Each entry contains: field1=value1, field2=value2, ...
Consumer Groups: Multiple consumers share the workload
Acknowledgment: Messages tracked until processed

2. XADD: Append to Stream

XADD appends a new entry to a stream. If the stream doesn't exist, it's created automatically.

Basic XADD

# Auto-generated ID (recommended)
XADD events * type click userId 1001 page /home
"1705312245123-0"

# Custom ID (rarely needed)
XADD events 1705312245123-0 type click userId 1001

# With max length (MAXLEN ~1000 keeps approximately 1000)
XADD events MAXLEN ~ 1000 * type click userId 1001

ID Options

  • * - Auto-generate (timestamp-sequence)
  • timestamp-seq - Explicit ID
  • timestamp-* - Custom time, auto sequence

Trimming Options

  • MAXLEN n - Exact max entries
  • MAXLEN ~ n - Approximate (faster)
  • MINID id - Remove older than ID

3. XREAD: Consume Messages

XREAD reads entries from one or more streams. It can block, waiting for new entries - like a real-time subscription.

Reading Streams

# Read from beginning
XREAD STREAMS events 0
1) 1) "events"
   2) 1) 1) "1705312245123-0"
         2) 1) "type"
            2) "click"
            3) "userId"
            4) "1001"

# Read new entries only (blocking)
XREAD BLOCK 5000 STREAMS events $
# Waits up to 5 seconds for new entries

# Read multiple streams
XREAD STREAMS events notifications 0 0

$ vs 0

Use 0 to read from the beginning of the stream. Use $ to read only new entries arriving after the command is issued. For catching up on history + new data, first read with 0, then switch to $ with the last received ID.

4. XRANGE: Query by ID Range

XRANGE returns entries between two IDs. Perfect for replay, time-range queries, and paginated reads.

Range Queries

# All entries
XRANGE events - +

# First 10 entries
XRANGE events - + COUNT 10

# Entries in time range (IDs are timestamp-based)
XRANGE events 1705312200000 1705312300000

# Reverse order
XREVRANGE events + - COUNT 10

Special IDs

  • - - Minimum ID (beginning)
  • + - Maximum ID (end)
  • timestamp - All entries at that millisecond

5. Consumer Groups

Consumer groups enable distributed processing. Multiple consumers share the work, each getting different messages. Messages are tracked until acknowledged.

Consumer Group Workflow

# Create a consumer group
XGROUP CREATE events mygroup $ MKSTREAM
# $ = start from new entries
# 0 = process entire history

# Read as a consumer
XREADGROUP GROUP mygroup consumer1 COUNT 10 STREAMS events >
# > = undelivered messages only

# Acknowledge processed message
XACK events mygroup 1705312245123-0

# Check pending messages (unacknowledged)
XPENDING events mygroup

# Claim stuck messages (consumer died)
XCLAIM events mygroup consumer2 3600000 1705312245123-0
# 3600000 = idle time threshold (1 hour)

Why Consumer Groups?

Without groups, every XREAD gets all messages. With groups, messages are distributed: consumer1 gets message A, consumer2 gets message B. Failed messages can be reclaimed by other consumers.

6. CLI vs Redimo

Stream data in CLI is verbose and hard to navigate. Each entry spans multiple lines with nested arrays.

CLI Output

127.0.0.1:6379> XRANGE events - + COUNT 3
1) 1) "1705312245123-0"
   2) 1) "type"
      2) "click"
      3) "userId"
      4) "1001"
      5) "page"
      6) "/home"
2) 1) "1705312245124-0"
   2) 1) "type"
      2) "purchase"
      3) "userId"
      4) "1001"
      5) "amount"
      6) "99.99"
3) 1) "1705312245125-0"
   2) ...

CLI Pain Points

  • • Nested array format is hard to parse visually
  • • No timeline view of events
  • • Difficult to filter by field values
  • • Consumer group status spread across multiple commands

Redimo View

  • • Stream entries in a clean table/timeline
  • • Entry fields as expandable JSON
  • • Filter and search within stream
  • • Consumer group dashboard with pending counts

7. Common Use Cases

Event Sourcing

# Log every state change
XADD order:1001:events * event created status pending
XADD order:1001:events * event payment_received amount 99.99
XADD order:1001:events * event shipped tracking ABC123

# Replay to rebuild state
XRANGE order:1001:events - +

Activity Feed

# Record activities
XADD feed:user:1001 MAXLEN ~ 100 * action liked target post:5001
XADD feed:user:1001 MAXLEN ~ 100 * action commented target post:5002

# Get recent activity
XREVRANGE feed:user:1001 + - COUNT 20

Task Queue with Acknowledgment

# Producer adds tasks
XADD tasks * type email to user@example.com subject "Hello"

# Workers process with consumer group
XGROUP CREATE tasks workers 0 MKSTREAM
XREADGROUP GROUP workers worker1 BLOCK 5000 STREAMS tasks >

# Acknowledge completed task
XACK tasks workers 1705312245123-0

8. Memory Management

Streams grow indefinitely without trimming. Set limits based on your use case:

Trimming Strategies

# Trim on every XADD
XADD events MAXLEN ~ 10000 * type click ...

# Manual trim by length
XTRIM events MAXLEN ~ 10000

# Trim by minimum ID (time-based)
XTRIM events MINID ~ 1705312200000-0

# Check stream length
XLEN events

# Get stream info
XINFO STREAM events

Approximate (~) Trimming

Using ~ allows Redis to trim more efficiently by removing whole radix tree nodes rather than individual entries. The actual count may be slightly higher than specified, but performance is better.

9. Pro Tips

ID as Timestamp

Stream IDs contain timestamps. You can query by time without storing timestamps separately: XRANGE events 1705312200000 1705312300000 gets entries from that time window.

XINFO for Debugging

XINFO STREAM events shows length, first/last entry, consumer groups. XINFO GROUPS events shows all consumer groups and their pending counts.

Stream Inspection

# Stream overview
XINFO STREAM events
1) "length"
2) (integer) 1000
3) "first-entry"
4) 1) "1705312245123-0"
   2) ...

# Consumer groups
XINFO GROUPS events
1) 1) "name"
   2) "mygroup"
   3) "consumers"
   4) (integer) 3
   5) "pending"
   6) (integer) 5

Start Building

Streams unlock powerful patterns: event sourcing, reliable queues, real-time feeds.
See your stream data clearly with Redimo.

Download Redimo - It's Free

Continue Learning

Beginner

GET & SET

Store and retrieve string values - the foundation of Redis

Beginner

HSET & HGET

Store objects as field-value pairs without JSON serialization

Beginner

LPUSH & RPUSH

Ordered collections for queues, stacks, and activity feeds

Beginner

SADD & SMEMBERS

Unique collections with powerful set operations

Free Download

Stop Fighting with CLI.
Visualize Your Data.

Redimo makes every Valkey and Redis command easier. Visual data, inline editing, Safe Mode for production.