XRANGE

Introduction and Use Case(s)

XRANGE is a Redis command used to read a range of entries from a stream. It’s highly useful in scenarios where you need to process or monitor data streams, such as event logging, messaging systems, or real-time analytics.

Syntax

  1. XRANGE key start end [COUNT count]

Parameter Explanations

  • key: The name of the stream.
  • start: The lower bound ID for the range (inclusive). Use - for the minimum possible ID.
  • end: The upper bound ID for the range (inclusive). Use + for the maximum possible ID.
  • COUNT count (optional): Limits the number of entries returned.

Return Values

XRANGE returns an array of stream entries, each entry being an array itself containing the entry ID and field-value pairs. If no entries exist within the specified range, an empty array is returned.

Example outputs:

  • When entries are found:

    1. 1) 1) "1609459200000-0"
    2.    2) 1) "field1"
    3.       2) "value1"
    4.       3) "field2"
    5.       4) "value2"

  • When no entries are found:

    1. (empty array)

Code Examples

  1. dragonfly> XADD mystream * field1 value1 field2 value2
  2. "1609459200000-0"
  3. dragonfly> XADD mystream * field1 value3 field2 value4
  4. "1609459200001-0"
  5. dragonfly> XRANGE mystream - +
  6. 1) 1) "1609459200000-0"
  7.    2) 1) "field1"
  8.       2) "value1"
  9.       3) "field2"
  10.       4) "value2"
  11. 2) 1) "1609459200001-0"
  12.    2) 1) "field1"
  13.       2) "value3"
  14.       3) "field2"
  15.       4) "value4"
  17. dragonfly> XRANGE mystream 1609459200000-0 1609459200000-0
  18. 1) 1) "1609459200000-0"
  19.    2) 1) "field1"
  20.       2) "value1"
  21.       3) "field2"
  22.       4) "value2"
  24. dragonfly> XRANGE mystream - + COUNT 1
  25. 1) 1) "1609459200000-0"
  26.    2) 1) "field1"
  27.       2) "value1"
  28.       3) "field2"
  29.       4) "value2"

Best Practices

  • Use COUNT to limit the number of entries returned, which can help manage memory and improve performance when working with large streams.

Common Mistakes

  • Specifying start greater than end will always return an empty array.
  • Forgetting to use double quotes around IDs that include special characters like -.

FAQs

What happens if I specify an ID that doesn’t exist?

The command will return entries with the closest higher IDs within the specified range.

Is there a way to get only new entries added to the stream?

For this purpose, use the XREAD command instead, which is designed to block and wait for new entries.