|
| 1 | +--- |
| 2 | +arguments: |
| 3 | +- name: key |
| 4 | + type: key |
| 5 | +- name: start |
| 6 | + type: string |
| 7 | +- name: end |
| 8 | + type: string |
| 9 | +- name: count |
| 10 | + optional: true |
| 11 | + type: integer |
| 12 | +arity: -4 |
| 13 | +categories: |
| 14 | +- docs |
| 15 | +- develop |
| 16 | +- stack |
| 17 | +- oss |
| 18 | +- rs |
| 19 | +- rc |
| 20 | +- oss |
| 21 | +- kubernetes |
| 22 | +- clients |
| 23 | +command_flags: |
| 24 | +- READONLY |
| 25 | +complexity: O(log(K)+M) where K is the number of elements in the start prefix, and |
| 26 | + M is the number of elements returned. In practical terms, the command is just O(M) |
| 27 | +description: Return elements in a lexicographical range |
| 28 | +function: vrangeCommand |
| 29 | +group: vector_set |
| 30 | +hidden: false |
| 31 | +linkTitle: VRANGE |
| 32 | +since: 8.4.0 |
| 33 | +summary: Return elements in a lexicographical range |
| 34 | +syntax_fmt: VRANGE key start end [count] |
| 35 | +syntax_str: start end [count] |
| 36 | +title: VRANGE |
| 37 | +--- |
| 38 | +The `VRANGE` command provides a stateless iterator for the elements inside a vector set. It allows you to retrieve all the elements inside a vector set in small amounts for each call, without an explicit cursor, and with guarantees about what you will miss in case the vector set is changing (elements added and/or removed) during the iteration. |
| 39 | + |
| 40 | +The command returns elements in lexicographical order, using byte-by-byte comparison (like `memcmp()`) to establish a total order among elements. |
| 41 | + |
| 42 | +## Required arguments |
| 43 | + |
| 44 | +<details open><summary><code>key</code></summary> |
| 45 | + |
| 46 | +The name of the vector set key from which to retrieve elements. |
| 47 | + |
| 48 | +</details> |
| 49 | + |
| 50 | +<details open><summary><code>start</code></summary> |
| 51 | + |
| 52 | +The starting point of the lexicographical range. Can be: |
| 53 | +- A string prefixed with `[` for inclusive range (e.g., `[Redis`) |
| 54 | +- A string prefixed with `(` for exclusive range (e.g., `(a7`) |
| 55 | +- The special symbol `-` to indicate the minimum element |
| 56 | + |
| 57 | +</details> |
| 58 | + |
| 59 | +<details open><summary><code>end</code></summary> |
| 60 | + |
| 61 | +The ending point of the lexicographical range. Can be: |
| 62 | +- A string prefixed with `[` for inclusive range |
| 63 | +- A string prefixed with `(` for exclusive range |
| 64 | +- The special symbol `+` to indicate the maximum element |
| 65 | + |
| 66 | +</details> |
| 67 | + |
| 68 | +## Optional arguments |
| 69 | + |
| 70 | +<details open><summary><code>count</code></summary> |
| 71 | + |
| 72 | +The maximum number of elements to return. If `count` is negative, the command returns all elements in the specified range (which may block the server for a long time with large sets). |
| 73 | + |
| 74 | +</details> |
| 75 | + |
| 76 | +## Examples |
| 77 | + |
| 78 | +Retrieve the first 10 elements starting from the string "Redis" (inclusive): |
| 79 | + |
| 80 | +``` |
| 81 | +VRANGE word_embeddings [Redis + 10 |
| 82 | +``` |
| 83 | + |
| 84 | +Iterate through all elements, 10 at a time: |
| 85 | + |
| 86 | +``` |
| 87 | +VRANGE mykey - + 10 |
| 88 | +``` |
| 89 | + |
| 90 | +Continue iteration from the last element of the previous result (exclusive): |
| 91 | + |
| 92 | +``` |
| 93 | +VRANGE mykey (a7 + 10 |
| 94 | +``` |
| 95 | + |
| 96 | +Return all elements in the set (use with caution): |
| 97 | + |
| 98 | +``` |
| 99 | +VRANGE mykey - + -1 |
| 100 | +``` |
| 101 | + |
| 102 | +## Return information |
| 103 | + |
| 104 | +{{< multitabs id="return-info" |
| 105 | + tab1="RESP2" |
| 106 | + tab2="RESP3" >}} |
| 107 | + |
| 108 | +One of the following: |
| 109 | + |
| 110 | +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of elements in lexicographical order within the specified range. |
| 111 | +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) (empty array) if the key doesn't exist. |
| 112 | + |
| 113 | +-tab-sep- |
| 114 | + |
| 115 | +One of the following: |
| 116 | + |
| 117 | +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of elements in lexicographical order within the specified range. |
| 118 | +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) (empty array) if the key doesn't exist. |
| 119 | + |
| 120 | +{{< /multitabs >}} |
| 121 | + |
| 122 | +## Behavior |
| 123 | + |
| 124 | +- **Iteration guarantees**: Each range will produce exactly the elements that were present in the range at the moment the `VRANGE` command was executed. |
| 125 | +- **Concurrent modifications**: Elements removed or added during iteration may or may not be returned, depending on when they were modified. |
| 126 | +- **Empty key**: If the key doesn't exist, returns an empty array. |
0 commit comments