XRANGE(3valkey)

📦

version 9.0.6 · 2 versions

9.0.6 · fedora 44 (latest)
8.1.10 · fedora 43

💖 XRANGE — the Valkey manual page, but make it make sense 💖

okay bestie, gather round, because XRANGE from the Valkey Command Manual is genuinely one of my faves and I'm about to make you obsessed with it. no cap. 🦋

✨ NAME ✨

xrange — returns the messages from a stream within a range of IDs. that's it. that's the whole vibe. 💅

✨ SYNOPSIS ✨

XRANGE key start end [COUNT count]

✨ DESCRIPTION ✨

so like, the tea is: this command gives you back the stream entries that match a given range of IDs. you hand it a minimum ID and a maximum ID, and everything with an ID between those two — or exactly equal to one of the two (closed interval, periodt) — comes back to you. 🎀

the XRANGE command has a bunch of applications, and honestly? all of them ate:

returning items in a specific time range. this is possible because Stream IDs are valkey-streams-intro(7) related to time. ⏰
iterating a stream incrementally, returning just a few items at every iteration. however it is semantically much more robust than the SCAN family of functions. (yes, that's a read. it's giving main character energy among iterators. 👑)
fetching a single entry from a stream, providing the ID of the entry to fetch two times: as start and end of the query interval.

the command also has a reciprocal command returning items in the reverse order, called XREVRANGE, which is otherwise identical. so like, its mirror twin. 🌈

💜 `-` and `+` special IDs

the - and + special IDs mean respectively the minimum ID possible and the maximum ID possible inside a stream, so the following command will just return every entry in the stream:

> XRANGE somestream - +
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"
2) 1) 1526985069902-0
   2) 1) "duration"
      2) "415"
      3) "event-id"
      4) "2"
      5) "user-id"
      6) "772213"
... other entries here ...

the - and + special IDs mean, respectively, the minimal and maximal range IDs, however they are nicer to type. like, keyboard-friendlier. way less to type, same amount of slay. ✨

💜 Incomplete IDs

Stream IDs are composed of two parts: a Unix millisecond time stamp and a sequence number for entries inserted in the same millisecond. it is possible to use XRANGE specifying just the first part of the ID, the millisecond time, like in the following example:

> XRANGE somestream 1526985054069 1526985055069

in this case, XRANGE will auto-complete the start interval with -0 and end interval with -18446744073709551615, in order to return all the entries that were generated between a given millisecond and the end of the other specified millisecond. this also means that repeating the same millisecond two times, we get all the entries within such millisecond, because the sequence number range will be from zero to the maximum. 😌

used in this way XRANGE works as a range query command to obtain entries in a specified time. this is very handy in order to access the history of past events in a stream. lowkey a time machine, fr fr. 🕰️

💜 Exclusive ranges

the range is close (inclusive) by default, meaning that the reply can include entries with IDs matching the query's start and end intervals. it is possible to specify an open interval (exclusive) by prefixing the ID with the character (. this is useful for iterating the stream, as explained below. 🫶

💜 Returning a maximum number of entries

using the COUNT option it is possible to reduce the number of entries reported. this is a very important feature even if it may look marginal, because it allows, for instance, to model operations such as give me the entry greater or equal to the following:

> XRANGE somestream 1526985054069-0 + COUNT 1
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"

in the above case the entry 1526985054069-0 exists, otherwise the server would have sent us the next one. using COUNT is also the base in order to use XRANGE as an iterator. 🎯

💜 Iterating a stream

in order to iterate a stream, we can proceed as follows. let's assume that we want two elements per iteration. we start fetching the first two elements, which is trivial:

> XRANGE writers - + COUNT 2
1) 1) 1526985676425-0
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) 1526985685298-0
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

then instead of starting the iteration again from -, as the start of the range we use the entry ID of the last entry returned by the previous XRANGE call as an exclusive interval.

the ID of the last entry is 1526985685298-0, so we just prefix it with a (, and continue our iteration:

> XRANGE writers (1526985685298-0 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
      3) "surname"
      4) "Morrison"
2) 1) 1526985712947-0
   2) 1) "name"
      2) "Agatha"
      3) "surname"
      4) "Christie"

and so forth. eventually this will allow to visit all the entries in the stream. obviously, we can start the iteration from any ID, or even from a specific time, by providing a given incomplete start ID. moreover, we can limit the iteration to a given ID or time, by providing an end ID or incomplete ID instead of +. 🌀

the command XREAD is also able to iterate the stream. the command XREVRANGE can iterate the stream reverse, from higher IDs (or times) to lower IDs (or times). options, options, options. 💫

💜 Fetching single items

if you look for an XGET command you'll be disappointed because XRANGE is effectively the way to go in order to fetch a single entry from a stream. all you have to do is to specify the ID two times in the arguments of XRANGE:

> XRANGE mystream 1526984818136-0 1526984818136-0
1) 1) 1526984818136-0
   2) 1) "duration"
      2) "1532"
      3) "event-id"
      4) "5"
      5) "user-id"
      6) "7782813"

same ID twice, no XGET, and yet it works. iconic behaviour honestly. 🙈

💜 Additional information about streams

for further information about streams please check our valkey-streams-intro(7) introduction to Streams document. go read it, bestie, it's the lore. 📖

✨ REPLY ✨

valkey-protocol(7) Array reply: a list of stream entries with IDs matching the specified range. just a whole array of your little stream entries. 💖

✨ COMPLEXITY ✨

O(N) with N being the number of elements being returned. if N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1). so like, keep your COUNT steady and you're basically free. ✨

✨ ACL CATEGORIES ✨

@read @slow @stream

✨ HISTORY ✨

Available since: 5.0.0 🌱
Changed in 6.2.0: Added exclusive ranges. 🎉

✨ EXAMPLES ✨

127.0.0.1:6379> XADD writers * name Virginia surname Woolf
"1714701492065-0"
127.0.0.1:6379> XADD writers * name Jane surname Austen
"1714701492075-0"
127.0.0.1:6379> XADD writers * name Toni surname Morrison
"1714701492084-0"
127.0.0.1:6379> XADD writers * name Agatha surname Christie
"1714701492094-0"
127.0.0.1:6379> XADD writers * name Ngozi surname Adichie
"1714701492104-0"
127.0.0.1:6379> XLEN writers
(integer) 5
127.0.0.1:6379> XRANGE writers - + COUNT 2
1) 1) "1714701492065-0"
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) "1714701492075-0"
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

look at the writers go. five of them, all added, all accounted for, and XRANGE pulls the first two like it's nothing. 🔥

ngl, that's a lot of stream commands. read them all, bestie, that's the whole X-family reunion. 🫶

okay that's the page!! this one's from version 9.0.0, dated 2025-10-21 — love that for us. mwah, go range some streams, you absolute legend. 💅💖✨🎀🦋🌸

📦 where this page comes from

fedora 44: valkey-doc 9.0.3-2.fc44 · CC-BY-SA-4.0
fedora 44: valkey-doc 9.0.6-1.fc44 · CC-BY-SA-4.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms