RedisJSON · oshadmi · Nov 14, 2022 · May 19, 2022 · Jun 13, 2022 · Jun 13, 2022
diff --git a/docs/commands/json.arrappend.md b/docs/commands/json.arrappend.md
@@ -1,18 +1,68 @@
-Append the `json` values into the array at `path` after the last element in it.
+Append the `json` values into the array at `path` after the last element in it
 
-@return
+[Examples](#examples)
 
-@array-reply of @integer-reply - for each path, the array's new size, or @nil-reply if the matching JSON value is not an array.
+## Required arguments
 
-@examples
+<details open><summary><code>key</code></summary> 
 
-```
-redis> JSON.SET doc $ '{"a":[1], "nested": {"a": [1,2]}, "nested2": {"a": 42}}'
+is key to modify.
+</details>
+
+<details open><summary><code>value</code></summary> 
+
+is one or more values to append to one or more arrays. 
+
+{{% alert title="About using strings with JSON commands" color="warning" %}}
+To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).
+{{% /alert %}}
+</details>
+
+## Optional arguments
+
+<details open><summary><code>path</code></summary> 
+
+is JSONPath to specify. Default is root `$`.
+</details>
+
+## Return value 
+
+`JSON.ARRAPEND` returns an [array](/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the array's new size, or `nil`, if the matching JSON value is not an array. 
+For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec). 
+
+## Examples
+
+<details open>
+<summary><b>Add a new color to a list of product colors</b></summary>
+
+Create a document for noise-cancelling headphones in black and silver colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
 OK
-redis> JSON.ARRAPPEND doc $..a 3 4
+{{< / highlight >}}
+
+Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
 1) (integer) 3
-2) (integer) 4
-3) (nil)
-redis> JSON.GET doc $
-"[{\"a\":[1,3,4],\"nested\":{\"a\":[1,2,3,4]},\"nested2\":{\"a\":42}}]"
-```
+{{< / highlight >}}
+
+Return the new length of the `colors` array.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.GET item:1
+"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
+{{< / highlight >}}
+
+</details>
+
+## See also
+
+`JSON.ARRINDEX` | `JSON.ARRINSERT` 
+
+## Related topics
+
+* [RedisJSON](/docs/stack/json)
+* [Index and search JSON documents](/docs/stack/search/indexing_json)
diff --git a/docs/commands/json.arrindex.md b/docs/commands/json.arrindex.md
@@ -1,29 +1,107 @@
-Searches for the first occurrence of a scalar JSON value in an array.
+Search for the first occurrence of a scalar JSON value in an array
 
-The optional inclusive `start` (default 0) and exclusive `stop` (default 0, meaning that the last element is included) specify a slice of the array to search.
-Negative values are interpreted as starting from the end.
+[Examples](#examples)
 
+## Required arguments
 
-Note: out-of-range indexes round to the array's start and end. An inverse index range (such as the range from 1 to 0) will return unfound.
+<details open><summary><code>key</code></summary> 
 
-@return
+is key to parse.
+</details>
 
-@array-reply of @integer-reply - the first position in the array of each JSON value that matches the path, -1 if unfound in the array, or @nil-reply if the matching JSON value is not an array.
+<details open><summary><code>value</code></summary> 
 
-@examples
+is value to find its index in one or more arrays. 
 
-```
-redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": [3,4]}}'
-OK
-redis> JSON.ARRINDEX doc $..a 2
-1) (integer) 1
-2) (integer) -1
-```
+{{% alert title="About using strings with JSON commands" color="warning" %}}
+To specify a string as an array value to index, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).
+{{% /alert %}}
+</details>
+
+## Optional arguments
+
+<details open><summary><code>start</code></summary> 
+
+is inclusive start value to specify in a slice of the array to search. Default is `0`. 
+</details>
+
+
+<details open><summary><code>stop</code></summary> 
+
+is exclusive stop value to specify in a slice of the array to search, including the last element. Default is `0`. Negative values are interpreted as starting from the end.
+</details>
 
-```
-redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
+{{% alert title="About out-of-range indexes" color="warning" %}}
+
+Out-of-range indexes round to the array's start and end. An inverse index range (such as the range from 1 to 0) returns unfound or `-1`.
+{{% /alert %}}
+
+## Return value 
+
+`JSON.ARRINDEX` returns an [array](/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the first position in the array of each JSON value that matches the path, `-1` if unfound in the array, or `nil`, if the matching JSON value is not an array.
+For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec). 
+
+## Examples
+
+<details open>
+<summary><b>Find the specific place of a color in a list of product colors</b></summary>
+
+Create a document for noise-cancelling headphones in black and silver colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
 OK
-redis> JSON.ARRINDEX doc $..a 2
+{{< / highlight >}}
+
+Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
+1) (integer) 3
+{{< / highlight >}}
+
+Return the new length of the `colors` array.
+
+{{< highlight bash >}}
+JSON.GET item:1
+"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
+{{< / highlight >}}
+
+Get the list of colors for the product.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.GET item:1 '$.colors[*]'
+"[\"black\",\"silver\",\"blue\"]"
+{{< / highlight >}}
+
+Insert two more colors after the second color. You now have five colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
+1) (integer) 5
+{{< / highlight >}}
+
+Get the updated list of colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.GET item:1 $.colors
+"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
+{{< / highlight >}}
+
+Find the place where color `silver` is located.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRINDEX item:1 $..colors '"silver"'
 1) (integer) 1
-2) (nil)
-```
+{{< / highlight >}}
+</details>
+
+## See also
+
+`JSON.ARRAPPEND` | `JSON.ARRINSERT` 
+
+## Related topics
+
+* [RedisJSON](/docs/stack/json)
+* [Index and search JSON documents](/docs/stack/search/indexing_json)
+
diff --git a/docs/commands/json.arrinsert.md b/docs/commands/json.arrinsert.md
@@ -1,28 +1,93 @@
-Inserts the `json` values into the array at `path` before the `index` (shifts to the right).
+Insert the `json` values into the array at `path` before the `index` (shifts to the right)
 
-The index must be in the array's range. Inserting at `index` 0 prepends to the array. Negative index values start from the end of the array.
+[Examples](#examples)
 
-@return
+## Required arguments
 
-@array-reply of @integer-reply - for each path, the array's new size, or @nil-reply if the matching JSON value is not an array.
+<details open><summary><code>key</code></summary> 
 
-@examples
+is key to modify.
+</details>
 
-```
-redis> JSON.SET doc $ '{"a":[3], "nested": {"a": [3,4]}}'
+<details open><summary><code>value</code></summary> 
+
+is one or more values to insert in one or more arrays. 
+
+{{% alert title="About using strings with JSON commands" color="warning" %}}
+To specify a string as an array value to insert, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).
+{{% /alert %}}
+</details>
+
+<details open><summary><code>index</code></summary> 
+
+is position in the array where you want to insert a value. The index must be in the array's range. Inserting at `index` 0 prepends to the array. Negative index values start from the end of the array.
+</details>
+
+## Optional arguments
+
+<details open><summary><code>path</code></summary> 
+
+is JSONPath to specify. Default is root `$`.
+</details>
+
+## Return value 
+
+`JSON.ARRINSERT` returns an [array](/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the array's new size, or `nil`, if the matching JSON value is not an array. 
+For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec). 
+
+## Examples
+
+<details open>
+<summary><b>Add new colors to a specific place in a list of product colors</b></summary>
+
+Create a document for noise-cancelling headphones in black and silver colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
 OK
-redis> JSON.ARRINSERT doc $..a 0 1 2
+{{< / highlight >}}
+
+Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
 1) (integer) 3
-2) (integer) 4
-redis> JSON.GET doc $
-"[{\"a\":[1,2,3],\"nested\":{\"a\":[1,2,3,4]}}]"
-```
+{{< / highlight >}}
 
-```
-redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
-OK
-redis> JSON.ARRINSERT doc $..a 0 1 2
-1) (integer) 6
-2) (nil)
-```
+Return the new length of the `colors` array.
+
+{{< highlight bash >}}
+JSON.GET item:1
+"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
+{{< / highlight >}}
+
+Get the list of colors for the product.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.GET item:1 '$.colors[*]'
+"[\"black\",\"silver\",\"blue\"]"
+{{< / highlight >}}
+
+Insert two more colors after the second color. You now have five colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
+1) (integer) 5
+{{< / highlight >}}
+
+Get the updated list of colors.
+
+{{< highlight bash >}}
+127.0.0.1:6379> JSON.GET item:1 $.colors
+"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
+{{< / highlight >}}
+</details>
+
+## See also
+
+`JSON.ARRAPPEND` | `JSON.ARRINDEX` 
+
+## Related topics
 
+* [RedisJSON](/docs/stack/json)
+* [Index and search JSON documents](/docs/stack/search/indexing_json)