Skip to content

Commit 9f48595

Browse files
nermillerrafie
nermiller
authored and
rafie
committed
[DOC] JSON command edits (RedisJSON#846)
* Partial fix for REDISIO-186: JSON broken links * Applied feedback from Chayim * Updates examples and restructures sections * Update docs/commands/json.arrappend.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrappend.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrindex.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrindex.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrinsert.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrindex.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrindex.md * Update docs/commands/json.arrinsert.md * Update docs/commands/json.arrlen.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrpop.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrtrim.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.numincrby.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.resp.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.set.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.strappend.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.toggle.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrpop.md * Update docs/commands/json.arrpop.md * Update docs/commands/json.arrinsert.md * Update json.arrtrim.md * Update docs/commands/json.arrappend.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrinsert.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrtrim.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> * Update docs/commands/json.arrpop.md Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> Co-authored-by: Omer Shadmi <76992134+oshadmi@users.noreply.github.com> (cherry picked from commit 112a4fa)
1 parent cd22071 commit 9f48595

22 files changed

+1246
-287
lines changed

‎docs/commands/json.arrappend.md

+62-12
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,68 @@
1-
Append the `json` values into the array at `path` after the last element in it.
1+
Append the `json` values into the array at `path` after the last element in it
22

3-
@return
3+
[Examples](#examples)
44

5-
@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.
5+
## Required arguments
66

7-
@examples
7+
<details open><summary><code>key</code></summary>
88

9-
```
10-
redis> JSON.SET doc $ '{"a":[1], "nested": {"a": [1,2]}, "nested2": {"a": 42}}'
9+
is key to modify.
10+
</details>
11+
12+
<details open><summary><code>value</code></summary>
13+
14+
is one or more values to append to one or more arrays.
15+
16+
{{% alert title="About using strings with JSON commands" color="warning" %}}
17+
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).
18+
{{% /alert %}}
19+
</details>
20+
21+
## Optional arguments
22+
23+
<details open><summary><code>path</code></summary>
24+
25+
is JSONPath to specify. Default is root `$`.
26+
</details>
27+
28+
## Return value
29+
30+
`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.
31+
For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec).
32+
33+
## Examples
34+
35+
<details open>
36+
<summary><b>Add a new color to a list of product colors</b></summary>
37+
38+
Create a document for noise-cancelling headphones in black and silver colors.
39+
40+
{{< highlight bash >}}
41+
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"]}'
1142
OK
12-
redis> JSON.ARRAPPEND doc $..a 3 4
43+
{{< / highlight >}}
44+
45+
Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
46+
47+
{{< highlight bash >}}
48+
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
1349
1) (integer) 3
14-
2) (integer) 4
15-
3) (nil)
16-
redis> JSON.GET doc $
17-
"[{\"a\":[1,3,4],\"nested\":{\"a\":[1,2,3,4]},\"nested2\":{\"a\":42}}]"
18-
```
50+
{{< / highlight >}}
51+
52+
Return the new length of the `colors` array.
53+
54+
{{< highlight bash >}}
55+
127.0.0.1:6379> JSON.GET item:1
56+
"{\"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\"]}"
57+
{{< / highlight >}}
58+
59+
</details>
60+
61+
## See also
62+
63+
`JSON.ARRINDEX` | `JSON.ARRINSERT`
64+
65+
## Related topics
66+
67+
* [RedisJSON](/docs/stack/json)
68+
* [Index and search JSON documents](/docs/stack/search/indexing_json)

‎docs/commands/json.arrindex.md

+97-19
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,107 @@
1-
Searches for the first occurrence of a scalar JSON value in an array.
1+
Search for the first occurrence of a scalar JSON value in an array
22

3-
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.
4-
Negative values are interpreted as starting from the end.
3+
[Examples](#examples)
54

5+
## Required arguments
66

7-
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.
7+
<details open><summary><code>key</code></summary>
88

9-
@return
9+
is key to parse.
10+
</details>
1011

11-
@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.
12+
<details open><summary><code>value</code></summary>
1213

13-
@examples
14+
is value to find its index in one or more arrays.
1415

15-
```
16-
redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": [3,4]}}'
17-
OK
18-
redis> JSON.ARRINDEX doc $..a 2
19-
1) (integer) 1
20-
2) (integer) -1
21-
```
16+
{{% alert title="About using strings with JSON commands" color="warning" %}}
17+
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).
18+
{{% /alert %}}
19+
</details>
20+
21+
## Optional arguments
22+
23+
<details open><summary><code>start</code></summary>
24+
25+
is inclusive start value to specify in a slice of the array to search. Default is `0`.
26+
</details>
27+
28+
29+
<details open><summary><code>stop</code></summary>
30+
31+
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.
32+
</details>
2233

23-
```
24-
redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
34+
{{% alert title="About out-of-range indexes" color="warning" %}}
35+
36+
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`.
37+
{{% /alert %}}
38+
39+
## Return value
40+
41+
`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.
42+
For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec).
43+
44+
## Examples
45+
46+
<details open>
47+
<summary><b>Find the specific place of a color in a list of product colors</b></summary>
48+
49+
Create a document for noise-cancelling headphones in black and silver colors.
50+
51+
{{< highlight bash >}}
52+
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"]}'
2553
OK
26-
redis> JSON.ARRINDEX doc $..a 2
54+
{{< / highlight >}}
55+
56+
Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
57+
58+
{{< highlight bash >}}
59+
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
60+
1) (integer) 3
61+
{{< / highlight >}}
62+
63+
Return the new length of the `colors` array.
64+
65+
{{< highlight bash >}}
66+
JSON.GET item:1
67+
"{\"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\"]}"
68+
{{< / highlight >}}
69+
70+
Get the list of colors for the product.
71+
72+
{{< highlight bash >}}
73+
127.0.0.1:6379> JSON.GET item:1 '$.colors[*]'
74+
"[\"black\",\"silver\",\"blue\"]"
75+
{{< / highlight >}}
76+
77+
Insert two more colors after the second color. You now have five colors.
78+
79+
{{< highlight bash >}}
80+
127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
81+
1) (integer) 5
82+
{{< / highlight >}}
83+
84+
Get the updated list of colors.
85+
86+
{{< highlight bash >}}
87+
127.0.0.1:6379> JSON.GET item:1 $.colors
88+
"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
89+
{{< / highlight >}}
90+
91+
Find the place where color `silver` is located.
92+
93+
{{< highlight bash >}}
94+
127.0.0.1:6379> JSON.ARRINDEX item:1 $..colors '"silver"'
2795
1) (integer) 1
28-
2) (nil)
29-
```
96+
{{< / highlight >}}
97+
</details>
98+
99+
## See also
100+
101+
`JSON.ARRAPPEND` | `JSON.ARRINSERT`
102+
103+
## Related topics
104+
105+
* [RedisJSON](/docs/stack/json)
106+
* [Index and search JSON documents](/docs/stack/search/indexing_json)
107+

‎docs/commands/json.arrinsert.md

+84-19
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,93 @@
1-
Inserts the `json` values into the array at `path` before the `index` (shifts to the right).
1+
Insert the `json` values into the array at `path` before the `index` (shifts to the right)
22

3-
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.
3+
[Examples](#examples)
44

5-
@return
5+
## Required arguments
66

7-
@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.
7+
<details open><summary><code>key</code></summary>
88

9-
@examples
9+
is key to modify.
10+
</details>
1011

11-
```
12-
redis> JSON.SET doc $ '{"a":[3], "nested": {"a": [3,4]}}'
12+
<details open><summary><code>value</code></summary>
13+
14+
is one or more values to insert in one or more arrays.
15+
16+
{{% alert title="About using strings with JSON commands" color="warning" %}}
17+
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).
18+
{{% /alert %}}
19+
</details>
20+
21+
<details open><summary><code>index</code></summary>
22+
23+
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.
24+
</details>
25+
26+
## Optional arguments
27+
28+
<details open><summary><code>path</code></summary>
29+
30+
is JSONPath to specify. Default is root `$`.
31+
</details>
32+
33+
## Return value
34+
35+
`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.
36+
For more information about replies, see [Redis serialization protocol specification](/docs/reference/protocol-spec).
37+
38+
## Examples
39+
40+
<details open>
41+
<summary><b>Add new colors to a specific place in a list of product colors</b></summary>
42+
43+
Create a document for noise-cancelling headphones in black and silver colors.
44+
45+
{{< highlight bash >}}
46+
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"]}'
1347
OK
14-
redis> JSON.ARRINSERT doc $..a 0 1 2
48+
{{< / highlight >}}
49+
50+
Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.
51+
52+
{{< highlight bash >}}
53+
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
1554
1) (integer) 3
16-
2) (integer) 4
17-
redis> JSON.GET doc $
18-
"[{\"a\":[1,2,3],\"nested\":{\"a\":[1,2,3,4]}}]"
19-
```
55+
{{< / highlight >}}
2056

21-
```
22-
redis> JSON.SET doc $ '{"a":[1,2,3,2], "nested": {"a": false}}'
23-
OK
24-
redis> JSON.ARRINSERT doc $..a 0 1 2
25-
1) (integer) 6
26-
2) (nil)
27-
```
57+
Return the new length of the `colors` array.
58+
59+
{{< highlight bash >}}
60+
JSON.GET item:1
61+
"{\"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\"]}"
62+
{{< / highlight >}}
63+
64+
Get the list of colors for the product.
65+
66+
{{< highlight bash >}}
67+
127.0.0.1:6379> JSON.GET item:1 '$.colors[*]'
68+
"[\"black\",\"silver\",\"blue\"]"
69+
{{< / highlight >}}
70+
71+
Insert two more colors after the second color. You now have five colors.
72+
73+
{{< highlight bash >}}
74+
127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
75+
1) (integer) 5
76+
{{< / highlight >}}
77+
78+
Get the updated list of colors.
79+
80+
{{< highlight bash >}}
81+
127.0.0.1:6379> JSON.GET item:1 $.colors
82+
"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
83+
{{< / highlight >}}
84+
</details>
85+
86+
## See also
87+
88+
`JSON.ARRAPPEND` | `JSON.ARRINDEX`
89+
90+
## Related topics
2891

92+
* [RedisJSON](/docs/stack/json)
93+
* [Index and search JSON documents](/docs/stack/search/indexing_json)

0 commit comments

Comments
 (0)