1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
Returns the specified range of elements in the sorted set stored at `<key>`.
`ZRANGE` can perform different types of range queries: by index (rank), by the
score, or by lexicographical order.
Starting with Redis 6.2.0, this command can replace the following commands:
`ZREVRANGE`, `ZRANGEBYSCORE`, `ZREVRANGEBYSCORE`, `ZRANGEBYLEX` and
`ZREVRANGEBYLEX`.
## Common behavior and options
The order of elements is from the lowest to the highest score. Elements with the
same score are ordered lexicographically.
The optional `REV` argument reverses the ordering, so elements are ordered from
highest to lowest score, and score ties are resolved by reverse lexicographical
ordering.
The optional `LIMIT` argument can be used to obtain a sub-range from the
matching elements (similar to _SELECT LIMIT offset, count_ in SQL). A negative
`<count>` returns all elements from the `<offset>`. Keep in mind that if
`<offset>` is large, the sorted set needs to be traversed for `<offset>`
elements before getting to the elements to return, which can add up to O(N) time
complexity.
The optional `WITHSCORES` argument supplements the command's reply with the
scores of elements returned. The returned list contains
`value1,score1,...,valueN,scoreN` instead of `value1,...,valueN`. Client
libraries are free to return a more appropriate data type (suggestion: an array
with (value, score) arrays/tuples).
## Index ranges
By default, the command performs an index range query. The `<min>` and `<max>`
arguments represent zero-based indexes, where `0` is the first element, `1` is
the next element, and so on. These arguments specify an **inclusive range**, so
for example, `ZRANGE myzset 0 1` will return both the first and the second
element of the sorted set.
The indexes can also be negative numbers indicating offsets from the end of the
sorted set, with `-1` being the last element of the sorted set, `-2` the
penultimate element, and so on.
Out of range indexes do not produce an error.
If `<min>` is greater than either the end index of the sorted set or `<max>`, an
empty list is returned.
If `<max>` is greater than the end index of the sorted set, Redis will use the
last element of the sorted set.
## Score ranges
When the `BYSCORE` option is provided, the command behaves like `ZRANGEBYSCORE`
and returns the range of elements from the sorted set having scores equal or
between `<min>` and `<max>`.
`<min>` and `<max>` can be `-inf` and `+inf`, denoting the negative and positive
infinities, respectively. This means that you are not required to know the
highest or lowest score in the sorted set to get all elements from or up to a
certain score.
By default, the score intervals specified by `<min>` and `<max>` are closed
(inclusive). It is possible to specify an open interval (exclusive) by prefixing
the score with the character `(`.
For example:
```
ZRANGE zset (1 5 BYSCORE
```
Will return all elements with `1 < score <= 5` while:
```
ZRANGE zset (5 (10 BYSCORE
```
Will return all the elements with `5 < score < 10` (5 and 10 excluded).
## Lexicographical ranges
When the `BYLEX` option is used, the command behaves like `ZRANGEBYLEX` and
returns the range of elements from the sorted set between the `<min>` and
`<max>` lexicographical closed range intervals.
Note that lexicographical ordering relies on all elements having the same score.
The reply is unspecified when the elements have different scores.
Valid `<min>` and `<max>` must start with `(` or `[`, in order to specify
whether the range interval is exclusive or inclusive, respectively.
The special values of `+` or `-` `<min>` and `<max>` mean positive and negative
infinite strings, respectively, so for instance the command **ZRANGEBYLEX
myzset - +** is guaranteed to return all the elements in the sorted set,
providing that all the elements have the same score.
### Lexicographical comparison of strings
Strings are compared as a binary array of bytes. Because of how the ASCII
character set is specified, this means that usually this also have the effect of
comparing normal ASCII characters in an obvious dictionary way. However, this is
not true if non-plain ASCII strings are used (for example, utf8 strings).
However, the user can apply a transformation to the encoded string so that the
first part of the element inserted in the sorted set will compare as the user
requires for the specific application. For example, if I want to add strings
that will be compared in a case-insensitive way, but I still want to retrieve
the real case when querying, I can add strings in the following way:
ZADD autocomplete 0 foo:Foo 0 bar:BAR 0 zap:zap
Because of the first _normalized_ part in every element (before the colon
character), we are forcing a given comparison. However, after the range is
queried using `ZRANGE ... BYLEX`, the application can display to the user the
second part of the string, after the colon.
The binary nature of the comparison allows to use sorted sets as a general
purpose index, for example, the first part of the element can be a 64-bit
big-endian number. Since big-endian numbers have the most significant bytes in
the initial positions, the binary comparison will match the numerical comparison
of the numbers. This can be used in order to implement range queries on 64-bit
values. As in the example below, after the first 8 bytes, we can store the value
of the element we are indexing.
@return
@array-reply: list of elements in the specified range (optionally with their
scores, in case the `WITHSCORES` option is given).
@history
- `>= 6.2`: Added the `REV`, `BYSCORE`, `BYLEX` and `LIMIT` options.
@examples
```cli
ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZRANGE myzset 0 -1
ZRANGE myzset 2 3
ZRANGE myzset -2 -1
```
The following example using `WITHSCORES` shows how the command returns always an
array, but this time, populated with _element_1_, _score_1_, _element_2_,
_score_2_, ..., _element_N_, _score_N_.
```cli
ZRANGE myzset 0 1 WITHSCORES
```
This example shows how to query the sorted set by score, excluding the value `1`
and up to infinity, returning only the second element of the result:
```cli
ZRANGE myzset (1 +inf BYSCORE LIMIT 1 1
```
|
