From 3fabf0b75561c061038f245acd3002b0007b6783 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Tue, 14 Oct 2025 09:42:23 -0700 Subject: [PATCH] DOC-5818: vector set: add new VRANGE command --- content/commands/vadd.md | 1 - content/commands/vcard.md | 1 - content/commands/vdim.md | 1 - content/commands/vemb.md | 1 - content/commands/vgetattr.md | 1 - content/commands/vinfo.md | 1 - content/commands/vismember.md | 1 - content/commands/vlinks.md | 1 - content/commands/vrandmember.md | 1 - content/commands/vrange.md | 126 ++++++++++++++++++ content/commands/vrem.md | 1 - content/commands/vsetattr.md | 1 - content/commands/vsim.md | 1 - .../develop/data-types/vector-sets/_index.md | 2 - 14 files changed, 126 insertions(+), 14 deletions(-) create mode 100644 content/commands/vrange.md diff --git a/content/commands/vadd.md b/content/commands/vadd.md index 735077229d..a2418d0a48 100644 --- a/content/commands/vadd.md +++ b/content/commands/vadd.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Add a new element to a vector set, or update its vector if it already exists. syntax_fmt: "VADD key [REDUCE dim] (FP32 | VALUES num) vector element [CAS] [NOQUANT | Q8 | BIN]\n [EF build-exploration-factor] [SETATTR attributes] [M numlinks]" title: VADD -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Add a new element into the vector set specified by `key`. The vector can be provided as 32-bit floating point (`FP32`) blob of values, or as floating point numbers as strings, prefixed by the number of elements (3 in the example below): diff --git a/content/commands/vcard.md b/content/commands/vcard.md index c0c1159085..ab77d1f7e3 100644 --- a/content/commands/vcard.md +++ b/content/commands/vcard.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return the number of elements in a vector set. syntax_fmt: "VCARD key" title: VCARD -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return the number of elements in the specified vector set. diff --git a/content/commands/vdim.md b/content/commands/vdim.md index c133f1d5a6..1a889812dc 100644 --- a/content/commands/vdim.md +++ b/content/commands/vdim.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return the dimension of vectors in the vector set. syntax_fmt: "VDIM key" title: VDIM -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return the number of dimensions of the vectors in the specified vector set. diff --git a/content/commands/vemb.md b/content/commands/vemb.md index 40eefa0249..5f2f0ab8a8 100644 --- a/content/commands/vemb.md +++ b/content/commands/vemb.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return the vector associated with an element. syntax_fmt: "VEMB key element [RAW]" title: VEMB -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return the approximate vector associated with a given element in the vector set. diff --git a/content/commands/vgetattr.md b/content/commands/vgetattr.md index 938b9dc7e6..3cfe7b4c29 100644 --- a/content/commands/vgetattr.md +++ b/content/commands/vgetattr.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Retrieve the JSON attributes of elements. syntax_fmt: "VGETATTR key element" title: VGETATTR -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return the JSON attributes associated with an element in a vector set. diff --git a/content/commands/vinfo.md b/content/commands/vinfo.md index a8a77485dc..9c29d75e9a 100644 --- a/content/commands/vinfo.md +++ b/content/commands/vinfo.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return information about a vector set. syntax_fmt: "VINFO key" title: VINFO -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return metadata and internal details about a vector set, including size, dimensions, quantization type, and graph structure. diff --git a/content/commands/vismember.md b/content/commands/vismember.md index 4093d1e32f..84e0cdd04b 100644 --- a/content/commands/vismember.md +++ b/content/commands/vismember.md @@ -28,7 +28,6 @@ summary: Check if an element exists in a vector set. syntax_fmt: VISMEMBER key element syntax_str: element title: VISMEMBER -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Check if an element exists in a vector set. diff --git a/content/commands/vlinks.md b/content/commands/vlinks.md index 4de1fd9091..cd1a53bf8b 100644 --- a/content/commands/vlinks.md +++ b/content/commands/vlinks.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return the neighbors of an element at each layer in the HNSW graph. syntax_fmt: "VLINKS key element [WITHSCORES]" title: VLINKS -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return the neighbors of a specified element in a vector set. The command shows the connections for each layer of the HNSW graph. diff --git a/content/commands/vrandmember.md b/content/commands/vrandmember.md index 26f751464b..ff08c68191 100644 --- a/content/commands/vrandmember.md +++ b/content/commands/vrandmember.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Return one or multiple random members from a vector set. syntax_fmt: "VRANDMEMBER key [count]" title: VRANDMEMBER -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return one or more random elements from a vector set. diff --git a/content/commands/vrange.md b/content/commands/vrange.md new file mode 100644 index 0000000000..6261330803 --- /dev/null +++ b/content/commands/vrange.md @@ -0,0 +1,126 @@ +--- +arguments: +- name: key + type: key +- name: start + type: string +- name: end + type: string +- name: count + optional: true + type: integer +arity: -4 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- READONLY +complexity: O(log(K)+M) where K is the number of elements in the start prefix, and + M is the number of elements returned. In practical terms, the command is just O(M) +description: Return elements in a lexicographical range +function: vrangeCommand +group: vector_set +hidden: false +linkTitle: VRANGE +since: 8.4.0 +summary: Return elements in a lexicographical range +syntax_fmt: VRANGE key start end [count] +syntax_str: start end [count] +title: VRANGE +--- +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. + +The command returns elements in lexicographical order, using byte-by-byte comparison (like `memcmp()`) to establish a total order among elements. + +## Required arguments + +
key + +The name of the vector set key from which to retrieve elements. + +
+ +
start + +The starting point of the lexicographical range. Can be: +- A string prefixed with `[` for inclusive range (e.g., `[Redis`) +- A string prefixed with `(` for exclusive range (e.g., `(a7`) +- The special symbol `-` to indicate the minimum element + +
+ +
end + +The ending point of the lexicographical range. Can be: +- A string prefixed with `[` for inclusive range +- A string prefixed with `(` for exclusive range +- The special symbol `+` to indicate the maximum element + +
+ +## Optional arguments + +
count + +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). + +
+ +## Examples + +Retrieve the first 10 elements starting from the string "Redis" (inclusive): + +``` +VRANGE word_embeddings [Redis + 10 +``` + +Iterate through all elements, 10 at a time: + +``` +VRANGE mykey - + 10 +``` + +Continue iteration from the last element of the previous result (exclusive): + +``` +VRANGE mykey (a7 + 10 +``` + +Return all elements in the set (use with caution): + +``` +VRANGE mykey - + -1 +``` + +## Return information + +{{< multitabs id="return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of elements in lexicographical order within the specified range. +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) (empty array) if the key doesn't exist. + +-tab-sep- + +One of the following: + +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of elements in lexicographical order within the specified range. +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) (empty array) if the key doesn't exist. + +{{< /multitabs >}} + +## Behavior + +- **Iteration guarantees**: Each range will produce exactly the elements that were present in the range at the moment the `VRANGE` command was executed. +- **Concurrent modifications**: Elements removed or added during iteration may or may not be returned, depending on when they were modified. +- **Empty key**: If the key doesn't exist, returns an empty array. diff --git a/content/commands/vrem.md b/content/commands/vrem.md index 227c1e65e2..ac5f01bed5 100644 --- a/content/commands/vrem.md +++ b/content/commands/vrem.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Remove an element from a vector set. syntax_fmt: "VREM key element" title: VREM -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Remove an element from a vector set. diff --git a/content/commands/vsetattr.md b/content/commands/vsetattr.md index 46688b309f..7362819f2c 100644 --- a/content/commands/vsetattr.md +++ b/content/commands/vsetattr.md @@ -18,7 +18,6 @@ since: 8.0.0 summary: Associate or remove the JSON attributes of elements. syntax_fmt: "VSETATTR key element \"{ JSON obj }\"" title: VSETATTR -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Associate a JSON object with an element in a vector set. Use this command to store attributes that can be used in filtered similarity searches with `VSIM`. diff --git a/content/commands/vsim.md b/content/commands/vsim.md index f7bb587ef8..0f8d5564d8 100644 --- a/content/commands/vsim.md +++ b/content/commands/vsim.md @@ -21,7 +21,6 @@ since: 8.0.0 summary: Return elements by vector similarity. syntax_fmt: "VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [WITHATTRIBS] [COUNT num]\n [EPSILON delta] [EF search-exploration-factor] [FILTER expression] [FILTER-EF max-filtering-effort]\n [TRUTH] [NOTHREAD]" title: VSIM -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- Return elements similar to a given vector or element. Use this command to perform approximate or exact similarity searches within a vector set. diff --git a/content/develop/data-types/vector-sets/_index.md b/content/develop/data-types/vector-sets/_index.md index b9046b705f..2baff73bf1 100644 --- a/content/develop/data-types/vector-sets/_index.md +++ b/content/develop/data-types/vector-sets/_index.md @@ -13,8 +13,6 @@ description: Introduction to Redis vector sets linkTitle: Vector sets title: Redis vector sets weight: 55 -bannerText: Vector set is a new data type that is currently in preview and may be subject to change. -bannerChildren: true --- Vector sets are a data type similar to sorted sets, but instead of a score, vector set elements have a string representation of a vector.