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.