ZRANGEBYSCORE

Introduction and Use Case(s)

The ZRANGEBYSCORE command in Redis is used to return the members of a sorted set whose scores fall within a specified range. This command is particularly useful for retrieving elements based on their ranking or priority, such as fetching leaderboard entries, scheduled tasks within a certain time frame, or items with specific score values.

Syntax

  1. ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]

Parameter Explanations

  • key: The name of the sorted set.
  • min: The minimum score (inclusive) of the range.
  • max: The maximum score (inclusive) of the range.
  • WITHSCORES (optional): Include this to return the scores of the elements in addition to the elements themselves.
  • LIMIT offset count (optional): Used to paginate through the results. offset specifies the number of elements to skip, and count specifies the maximum number of elements to return.

Return Values

The command returns an array of elements in the specified score range. If WITHSCORES is used, the array will alternate between elements and their respective scores.

Examples:

  • Without WITHSCORES:

    1. ["element1", "element2", "element3"]

  • With WITHSCORES:

    1. ["element1", "1.0", "element2", "2.0", "element3", "3.0"]

Code Examples

  1. dragonfly> ZADD myzset 1 "one" 2 "two" 3 "three"
  2. (integer) 3
  3. dragonfly> ZRANGEBYSCORE myzset 1 2
  4. 1) "one"
  5. 2) "two"
  6. dragonfly> ZRANGEBYSCORE myzset 1 2 WITHSCORES
  7. 1) "one"
  8. 2) "1"
  9. 3) "two"
  10. 4) "2"
  11. dragonfly> ZRANGEBYSCORE myzset 2 3 LIMIT 1 1
  12. 1) "three"

Best Practices

  • Use WITHSCORES only when necessary to avoid additional memory overhead.
  • Apply the LIMIT option for large sorted sets to manage memory usage and improve performance.
  • Ensure min and max are set appropriately to avoid unexpected results.

Common Mistakes

  • Using min and max incorrectly: Ensure that min <= max.
  • Omitting WITHSCORES when scores are needed for further processing, which leads to additional queries.

FAQs

Q: Can I use negative scores with ZRANGEBYSCORE? A: Yes, both min and max can be negative numbers.

Q: What happens if no elements fall within the given score range? A: An empty array will be returned.

Q: How does Redis handle non-numeric min or max values? A: Redis will return an error as min and max must be valid numeric values or special strings like -inf and +inf.