Merge branch 'feat-ros-8.2' of github.com:redis/docs into feat-ros-8.2

dwdougherty · dwdougherty · commit 508402901da2 · 2025-06-30T11:21:22.000-07:00
diff --git a/content/commands/bitop.md b/content/commands/bitop.md
@@ -21,6 +21,22 @@ arguments:
     name: not
     token: NOT
     type: pure-token
+  - display_text: diff
+    name: diff
+    token: DIFF
+    type: pure-token
+  - display_text: diff1
+    name: diff1
+    token: DIFF1
+    type: pure-token
+  - display_text: andor
+    name: andor
+    token: ANDOR
+    type: pure-token
+  - display_text: one
+    name: one
+    token: ONE
+    type: pure-token
   name: operation
   type: oneof
 - display_text: destkey
@@ -78,26 +94,45 @@ key_specs:
 linkTitle: BITOP
 since: 2.6.0
 summary: Performs bitwise operations on multiple strings, and stores the result.
-syntax_fmt: BITOP <AND | OR | XOR | NOT> destkey key [key ...]
+syntax_fmt: "BITOP <AND | OR | XOR | NOT | DIFF | DIFF1 | ANDOR | ONE> destkey key [key ...]"
 syntax_str: destkey key [key ...]
 title: BITOP
 ---
 Perform a bitwise operation between multiple keys (containing string values) and
 store the result in the destination key.
 
-The `BITOP` command supports four bitwise operations: **AND**, **OR**, **XOR**
-and **NOT**, thus the valid forms to call the command are:
+The `BITOP` command supports eight bitwise operations: `AND`, `OR`, `XOR`,
+`NOT`, `DIFF`, `DIFF1`, `ANDOR`, and `ONE`. The valid forms to call the command are:
 
 
 * `BITOP AND destkey srckey1 srckey2 srckey3 ... srckeyN`
+
+    A bit in `destkey` is set only if it is set in all source bitmaps.
 * `BITOP OR  destkey srckey1 srckey2 srckey3 ... srckeyN`
+
+    A bit in `destkey` is set only if it is set in at least one source bitmap.
 * `BITOP XOR destkey srckey1 srckey2 srckey3 ... srckeyN`
+
+    Mostly used with two source bitmaps, a bit in `destkey` is set only if its value differs between the two source bitmaps.
 * `BITOP NOT destkey srckey`
 
-As you can see **NOT** is special as it only takes an input key, because it
-performs inversion of bits so it only makes sense as a unary operator.
+    `NOT` is a unary operator and only supports a single source bitmap; set the bit to the inverse of its value in the source bitmap.
+* `BITOP DIFF destkey X [Y1 Y2 ...]` <sup>[1](#list-note-1)</sup>
+
+    A bit in `destkey` is set if it is set in `X`, but not in any of `Y1, Y2, ...` .
+* `BITOP DIFF1 destkey X [Y1 Y2 ...]` <sup>[1](#list-note-1)</sup>
 
-The result of the operation is always stored at `destkey`.
+    A bit in `destkey` is set if it is set in one or more of `Y1, Y2, ...`, but not in `X`.
+* `BITOP ANDOR destkey X [Y1 Y2 ...]` <sup>[1](#list-note-1)</sup>
+
+    A bit in `destkey` is set if it is set in `X` and also in one or more of `Y1, Y2, ...`.
+* `BITOP ONE destkey X1 [X2 X3 ...]` <sup>[1](#list-note-1)</sup>
+
+    A bit in `destkey` is set if it is set in exactly one of `X1, X2, ...`.
+
+The result of each operation is always stored at `destkey`.
+
+1. <a name="list-note-1"></a> Added in Redis 8.2.
 
 ## Handling of strings with different lengths
 
@@ -110,13 +145,27 @@ zero bytes up to the length of the longest string.
 
 ## Examples
 
+1. Basic usage example using the `AND` operator:
+
 {{% redis-cli %}}
-SET key1 "foobar"
-SET key2 "abcdef"
+BITFIELD key1 SET i8 #0 255
+BITFIELD key2 SET i8 #0 85
 BITOP AND dest key1 key2
-GET dest
+BITFIELD dest GET i8 #0
 {{% /redis-cli %}}
 
+2. Suppose you want to expose people to a book-related ad. The target audience is people who love to read books and are interested in fantasy, adventure, or science fiction. Assume you have the following bitmaps:
+
+* `LRB` - people who love to read books.
+* `B:F` - people interested in fantasy.
+* `B:A` - people interested in adventure.
+* `B:SF` - people interested in science fiction.
+
+To create a bitmap representing the target audience, use the following command:
+
+```
+BITOP ANDOR TA LRB B:F B:A B:SF
+```
 
 ## Pattern: real time metrics using bitmaps
 
diff --git a/content/commands/cluster-slot-stats.md b/content/commands/cluster-slot-stats.md
@@ -0,0 +1,129 @@
+---
+arguments:
+- arguments:
+  - arguments:
+    - name: start-slot
+      type: integer
+    - name: end-slot
+      type: integer
+    name: slotsrange
+    token: SLOTSRANGE
+    type: block
+  - arguments:
+    - name: metric
+      type: string
+    - name: limit
+      optional: true
+      token: LIMIT
+      type: integer
+    - arguments:
+      - name: asc
+        token: ASC
+        type: pure-token
+      - name: desc
+        token: DESC
+        type: pure-token
+      name: order
+      optional: true
+      type: oneof
+    name: orderby
+    token: ORDERBY
+    type: block
+  name: filter
+  type: oneof
+arity: -4
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- STALE
+- LOADING
+command_tips:
+- NONDETERMINISTIC_OUTPUT
+- REQUEST_POLICY:ALL_SHARDS
+complexity: O(N) where N is the total number of slots based on arguments. O(N*log(N))
+  with ORDERBY subcommand.
+container: CLUSTER
+description: Return an array of slot usage statistics for slots assigned to the current
+  node.
+function: clusterSlotStatsCommand
+group: cluster
+hidden: false
+linkTitle: CLUSTER SLOT-STATS
+reply_schema:
+  description: Array of nested arrays, where the inner array element represents a
+    slot and its respective usage statistics.
+  items:
+    description: Array of size 2, where 0th index represents (int) slot and 1st index
+      represents (map) usage statistics.
+    items:
+    - description: Slot Number.
+      type: integer
+    - additionalProperties: false
+      description: Map of slot usage statistics.
+      properties:
+        cpu-usec:
+          type: integer
+        key-count:
+          type: integer
+        network-bytes-in:
+          type: integer
+        network-bytes-out:
+          type: integer
+      type: object
+    maxItems: 2
+    minItems: 2
+    type: array
+  type: array
+since: 8.2.0
+summary: Return an array of slot usage statistics for slots assigned to the current
+  node.
+syntax_fmt: "CLUSTER SLOT-STATS <SLOTSRANGE\_start-slot end-slot | ORDERBY\_metric\n  [LIMIT\_\
+  limit] [ASC | DESC]>"
+syntax_str: ''
+title: CLUSTER SLOT-STATS
+---
+
+Use this command to get an array of slot usage statistics for the slots assigned to the current shard. If you're working with a Redis cluster, this data helps you understand overall slot usage, spot hot or cold slots, plan slot migrations to balance load, or refine your application logic to better distribute keys.
+
+## Options
+
+`CLUSTER SLOT-STATS` has two mutually exclusive options:
+
+* `ORDERBY`: Sorts the slot statistics by the specified metric. Use ASC or DESC to sort in ascending or descending order. If multiple slots have the same value, the command uses the slot number as a tiebreaker, sorted in ascending order.
+
+* `SLOTSRANGE`: Limits the results to a specific, inclusive range of slots. Results are always sorted by slot number in ascending order.
+
+The command reports on the following statistics:
+
+* `KEY-COUNT`: Number of keys stored in the slot.
+* `CPU-USEC`: CPU time (in microseconds) spent handling the slot.
+* `NETWORK-BYTES-IN`: Total inbound network traffic (in bytes) received by the slot.
+* `NETWORK-BYTES-OUT`: Total outbound network traffic (in bytes) sent from the slot.
+
+## Return information
+
+{{< multitabs id=“cmd-name-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a nested list of slot usage statistics.
+* [Simple error]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) otherwise.
+
+-tab-sep-
+
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a nested list of slot usage statistics.
+* [Simple error]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) otherwise.
+
+{{< /multitabs >}}
diff --git a/content/commands/vsim.md b/content/commands/vsim.md
@@ -13,10 +13,13 @@ complexity: O(log(N)) where N is the number of elements in the vector set.
 description: Return elements by vector similarity.
 group: vector_set
 hidden: false
+history:
+- - 8.2.0
+  - added the WITHATTRIBS option.
 linkTitle: VSIM
 since: 8.0.0
 summary: Return elements by vector similarity.
-syntax_fmt: "VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [COUNT num] [EF search-exploration-factor]\n  [FILTER expression] [FILTER-EF max-filtering-effort] [TRUTH] [NOTHREAD]"
+syntax_fmt: "VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [WITHATTRIBS] [COUNT num]\n  [EF search-exploration-factor] [FILTER expression] [FILTER-EF max-filtering-effort] [TRUTH] [NOTHREAD]"
 title: VSIM
 bannerText: Vector set is a new data type that is currently in preview and may be subject to change.
 ---
@@ -39,16 +42,19 @@ VSIM word_embeddings ELE apple
 10) "grape"
 ```
 
-You can include similarity scores and limit the number of results:
+You can include similarity scores, attributes (if any), and limit the number of results:
 
 ```shell
-VSIM word_embeddings ELE apple WITHSCORES COUNT 3
+VSIM word_embeddings ELE apple WITHSCORES WITHATTRIBS COUNT 3
 1) "apple"
 2) "0.9998867657923256"
-3) "apples"
-4) "0.8598527610301971"
-5) "pear"
-6) "0.8226882219314575"
+3) "{\"len\": 5}"
+4) "apples"
+5) "0.859852746129036"
+6) "{\"len\": 6}"
+7) "pear"
+8) "0.8226882070302963"
+9) "{\"len\": 4}"
 ```
 
 Set the `EF` (exploration factor) to improve recall at the cost of performance. Use the `TRUTH` option to perform an exact linear scan, useful for benchmarking. The `NOTHREAD` option runs the search in the main thread and may increase server latency.
@@ -81,6 +87,12 @@ is either the vector data (for `FP32` or `VALUES`) or the name of the element (f
 returns the similarity score (from 1 to 0) alongside each result. A score of 1 is identical; 0 is the opposite.
 </details>
 
+<details open>
+<summary><code>WITHATTRIBS</code></summary>
+
+returns, for each element, the JSON attribute associated with the element or NULL when no attributes are present.
+</details>
+
 <details open>
 <summary><code>COUNT num</code></summary>
 
@@ -128,16 +140,19 @@ executes the search in the main thread instead of a background thread. Useful fo
     tab2="RESP3" >}}
 
 One of the following:
-* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for unknown element.
-* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for unknown key.
-* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements; juxtaposed with scores when used with the WITHSCORES option.
+* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for an unknown element.
+* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for an unknown key.
+* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements.
+* With the `WITHSCORES` option, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements juxtaposed with [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) as floating-point scores.
+* With the `WITHSCORES` and `WITHATTRIBS` options, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements, and two additional elements: (1) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) as floating-point score and (2) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the JSON attribute associated with the element or [nil (null bulk string)]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) for the elements missing an attribute.
 
 -tab-sep-
 
 One of the following:
 * [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for unknown element.
 * [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for unknown key.
 * [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements.
-* [Map reply](../../develop/reference/protocol-spec#maps) with matching elements and [double](../../develop/reference/protocol-spec#doubles) scores when used with the WITHSCORES option.
+* With the `WITHSCORES` option, a [map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements (keys) and  [double](../../develop/reference/protocol-spec#doubles) scores (values).
+* With the `WITHSCORES` and `WITHATTRIBS` options, a [Map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements (keys), and an additional array (values) with the following elements: (1) a [double reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})  for the score and (2) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the JSON attribute associated with the element or [null]({{< relref "/develop/reference/protocol-spec#nulls" >}}) for the elements missing an attribute.
 
 {{< /multitabs >}}
diff --git a/content/develop/data-types/bitmaps.md b/content/develop/data-types/bitmaps.md
@@ -9,9 +9,7 @@ categories:
 - oss
 - kubernetes
 - clients
-description: 'Introduction to Redis bitmaps
-
-  '
+description: Introduction to Redis bitmaps
 linkTitle: Bitmaps
 title: Redis bitmaps
 weight: 120
@@ -79,7 +77,7 @@ stored into the target key) are always considered to be zero.
 
 There are three commands operating on group of bits:
 
-1. [`BITOP`]({{< relref "/commands/bitop" >}}) performs bit-wise operations between different strings. The provided operations are AND, OR, XOR and NOT.
+1. [`BITOP`]({{< relref "/commands/bitop" >}}) performs bit-wise operations between different strings. The provided operators are `AND`, `OR`, `XOR`, `NOT`, `DIFF`, `DIFF1`, `ANDOR`, and `ONE`.
 2. [`BITCOUNT`]({{< relref "/commands/bitcount" >}}) performs population counting, reporting the number of bits set to 1.
 3. [`BITPOS`]({{< relref "/commands/bitpos" >}}) finds the first bit having the specified value of 0 or 1.
 
