# XRANGE

> Return the stream entries with IDs in a range, oldest first.

URL: https://docs.hotkv.com/commands/xrange/

```
XRANGE key start end [COUNT count]
```

- Group: Stream
- Complexity: O(log N + M), M being the entries returned
- HotKV Cloud: all plans
- On-Premise: no license needed

`XRANGE` returns the entries of the stream at `key` whose IDs lie between
`start` and `end`, both included, in ascending ID order.

## Range bounds

| Bound | Meaning |
| --- | --- |
| `-` | The lowest possible ID. |
| `+` | The highest possible ID. |
| `ms-seq` | That exact ID. |
| `ms` | As `start`, the first ID of that millisecond (`ms-0`); as `end`, the last one. |
| `(` before an ID | Exclude that ID (an exclusive bound). |

## Options

| Option | Effect |
| --- | --- |
| `COUNT count` | Return at most `count` entries. |

## Return value

An array of entries. Each entry is a two-element array: the ID as a bulk
string, then a flat array of field and value bulk strings. The shape is the
same in RESP2 and RESP3.

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Entries in range | Array of entries | Array of entries |
| Nothing in range, or no such key | Empty array | Empty array |
| `COUNT` of 0 or less on an existing stream | Nil array | Null |

Error replies:

- `ERR Invalid stream ID specified as stream command argument` for a bound that does not parse.
- `ERR invalid start ID for the interval` or `ERR invalid end ID for the interval` for an exclusive bound that has no ID after (or before) it, such as `(0-0` as the end.
- `ERR syntax error` for an argument other than `COUNT count`.
- `ERR value is not an integer or out of range` for a bad count.
- `WRONGTYPE` if the key holds another type.

## Examples

```
127.0.0.1:6379> XADD log 1700000000000-0 level info msg start
"1700000000000-0"
127.0.0.1:6379> XADD log 1700000000000-1 level warn msg slow
"1700000000000-1"
127.0.0.1:6379> XADD log 1700000000005-0 level info msg done
"1700000000005-0"
127.0.0.1:6379> XRANGE log - + COUNT 2
1) 1) "1700000000000-0"
   2) 1) "level"
      2) "info"
      3) "msg"
      4) "start"
2) 1) "1700000000000-1"
   2) 1) "level"
      2) "warn"
      3) "msg"
      4) "slow"
127.0.0.1:6379> XRANGE log (1700000000000-1 +
1) 1) "1700000000005-0"
   2) 1) "level"
      2) "info"
      3) "msg"
      4) "done"
127.0.0.1:6379> XRANGE log 1700000000005 +
1) 1) "1700000000005-0"
   2) 1) "level"
      2) "info"
      3) "msg"
      4) "done"
```

## Compatibility

Same as Redis 7 and Valkey 8, including exclusive ranges.

## See also

[XREVRANGE](https://docs.hotkv.com/commands/xrevrange/index.md), [XREAD](https://docs.hotkv.com/commands/xread/index.md), [XADD](https://docs.hotkv.com/commands/xadd/index.md),
[XLEN](https://docs.hotkv.com/commands/xlen/index.md)