# ZRANGE

> Get a range of members from a sorted set by rank, score or lexicographic order.

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

```
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]
```

- Group: Sorted set
- Complexity: O(log(N)+M) where N is the size of the sorted set and M is the number of members returned
- HotKV Cloud: all plans
- On-Premise: no license needed

`ZRANGE` returns members of the sorted set at `key` in a range. What `start`
and `stop` mean depends on the options:

- **By rank** (default): `start` and `stop` are zero-based positions, both
  included. Negative values count from the end, so `ZRANGE key 0 -1` returns
  everything. Out-of-range positions are clamped.
- **`BYSCORE`**: `start` and `stop` are scores. They are inclusive unless
  prefixed with `(`, and `-inf` / `+inf` are allowed.
- **`BYLEX`**: `start` and `stop` are lexicographic bounds: `[value`
  (inclusive), `(value` (exclusive), `-` or `+`. Use this when all members
  share the same score.

Members come back from the lowest score to the highest (ties in lexicographic
order). `REV` reverses the order; with `BYSCORE` or `BYLEX` and `REV`, give the
higher bound first.

## Options

| Option | Effect |
| --- | --- |
| `BYSCORE` | Treat `start` and `stop` as scores. |
| `BYLEX` | Treat `start` and `stop` as lexicographic bounds. |
| `REV` | Return members from the highest to the lowest. |
| `LIMIT offset count` | Skip `offset` matching members, then return at most `count`. A negative `count` returns all remaining members; a negative `offset` returns nothing. Only with `BYSCORE` or `BYLEX`. |
| `WITHSCORES` | Return each member with its score. Not allowed with `BYLEX`. |

`BYSCORE` and `BYLEX` cannot be combined, and `BYSCORE`, `BYLEX` and `REV` can
each be given once. Options are checked before the range and the key.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Success | Array of members | Same |
| With `WITHSCORES` | Flat array: member, score, member, score, ... (scores as bulk strings) | Array of two-element arrays: `[member, score]`, the score a double |
| Key does not exist or empty range | Empty array | Same |

Errors:

- `ERR syntax error` for an unknown, repeated or conflicting option.
- ``ERR syntax error, LIMIT is only supported in combination with either BYSCORE or BYLEX``.
- ``ERR syntax error, WITHSCORES not supported in combination with BYLEX``.
- `ERR value is not an integer or out of range` for a non-integer rank or
  `LIMIT` value.
- `ERR min or max is not a float` for a bad score bound.
- `ERR min or max not valid string range item` for a bad lexicographic bound.
- `WRONGTYPE` if `key` holds a value that is not a sorted set.

## Examples

```
127.0.0.1:6379> ZADD board 1 "a" 2 "b" 3 "c" 4 "d"
(integer) 4
127.0.0.1:6379> ZRANGE board 0 1 WITHSCORES
1) "a"
2) "1"
3) "b"
4) "2"
127.0.0.1:6379> ZRANGE board (1 +inf BYSCORE LIMIT 0 2
1) "b"
2) "c"
127.0.0.1:6379> ZRANGE board +inf 3 BYSCORE REV
1) "d"
2) "c"
127.0.0.1:6379> ZRANGE board 0 -1 REV
1) "d"
2) "c"
3) "b"
4) "a"
```

## Compatibility

Same as Redis 7.4 and Valkey 8.

## See also

[ZRANGESTORE](https://docs.hotkv.com/commands/zrangestore/index.md), [ZRANGEBYSCORE](https://docs.hotkv.com/commands/zrangebyscore/index.md),
[ZRANGEBYLEX](https://docs.hotkv.com/commands/zrangebylex/index.md), [ZREVRANGE](https://docs.hotkv.com/commands/zrevrange/index.md), [ZRANK](https://docs.hotkv.com/commands/zrank/index.md)