Skip to content

Commit 84f9179

Browse files
mrhhsgmrhhsg
authored
update json functions' document (#2640)
## Versions - [x] dev - [ ] 3.0 - [ ] 2.1 - [ ] 2.0 ## Languages - [x] Chinese - [x] English ## Docs Checklist - [ ] Checked by AI - [ ] Test Cases Built
1 parent 6aa2398 commit 84f9179

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1025
-1639
lines changed

‎docs/sql-manual/sql-functions/scalar-functions/json-functions/json-contains.md

Lines changed: 79 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -7,62 +7,89 @@
77

88
## Description
99

10-
This function is used to check whether a JSON document contains a specified JSON element. If the specified element exists in the JSON document, it returns 1; otherwise, it returns 0. If the JSON document or the queried element is invalid, it returns `NULL`.
10+
Used to determine whether a JSON document contains a specified JSON element. If the specified element exists in the JSON document, it returns 1, otherwise it returns 0. If the JSON document or the queried element is invalid, it returns `NULL`.
1111

1212
## Syntax
1313

14-
`JSON_CONTAINS(<json_str>, <candidate> [, <json_path>])`
15-
16-
## Required Parameters
17-
18-
| Parameter | Description |
19-
|-------------|-----------------------------------------------------|
20-
| `<json_str>` | The JSON string to be checked. |
21-
| `<candidate>` | The JSON element to check for inclusion. |
22-
23-
## Optional Parameters
24-
25-
| Parameter | Description |
26-
|-------------|-----------------------------------------------------|
27-
| `<json_path>` | An optional JSON path to specify the subdocument to check. If not provided, the root document is used by default. |
28-
29-
## Return Value
30-
- If `<json_path>` exists in `json_doc`, it returns 1.
31-
- If `<json_path>` does not exist in `json_doc`, it returns 0.
32-
- If any parameter is invalid or the JSON document format is incorrect, it returns `NULL`.
33-
34-
## Examples
35-
36-
```sql
37-
38-
SELECT JSON_CONTAINS('{"a": 1, "b": 2, "c": {"d": 4}}', '1', '$.a');
39-
40-
```
41-
4214
```sql
43-
+------------------------------------------------------------------------------------------+
44-
| json_contains(cast('{"a": 1, "b": 2, "c": {"d": 4}}' as JSON), cast('1' as JSON), '$.a') |
45-
+------------------------------------------------------------------------------------------+
46-
| 1 |
47-
+------------------------------------------------------------------------------------------+
48-
15+
JSON_CONTAINS(<json_object>, <candidate>[, <json_path>])
4916
```
5017

18+
## Parameters
19+
### Required Parameters
20+
- `<json_object>` JSON type, check whether `<candidate>` exists in it.
21+
- `<candidate>` JSON type, the candidate value to be determined.
22+
### Optional Parameters
23+
- `<json_path>` String type, the search starting path. If not provided, it starts from root by default.
5124

52-
```sql
53-
54-
SELECT json_contains('[1, 2, {"x": 3}]', '1');
55-
56-
```
57-
58-
```sql
59-
+-------------------------------------------------------------------------+
60-
| json_contains(cast('[1, 2, {"x": 3}]' as JSON), cast('1' as JSON), '$') |
61-
+-------------------------------------------------------------------------+
62-
| 1 |
63-
+-------------------------------------------------------------------------+
64-
65-
```
66-
67-
68-
25+
## Return Value
26+
- Null: If any of the three parameters is NULL, returns NULL
27+
- True: If `<json_object>` contains `<candidate>`, returns True.
28+
- False: If `<json_object>` does not contain `<candidate>`, returns False.
29+
- If `<json_object>` or `<candidate>` is not a JSON type, an error is reported.
30+
31+
## Examples
32+
1. Example 1
33+
```sql
34+
SET @j = '{"a": 1, "b": 2, "c": {"d": 4}}';
35+
SET @j2 = '1';
36+
SELECT JSON_CONTAINS(@j, @j2, '$.a');
37+
```
38+
```text
39+
+-------------------------------+
40+
| JSON_CONTAINS(@j, @j2, '$.a') |
41+
+-------------------------------+
42+
| 1 |
43+
+-------------------------------+
44+
```
45+
```sql
46+
SELECT JSON_CONTAINS(@j, @j2, '$.b');
47+
```
48+
```text
49+
+-------------------------------+
50+
| JSON_CONTAINS(@j, @j2, '$.b') |
51+
+-------------------------------+
52+
| 0 |
53+
+-------------------------------+
54+
```
55+
```sql
56+
SELECT JSON_CONTAINS(@j, '{"a": 1}');
57+
```
58+
```text
59+
+-------------------------------+
60+
| JSON_CONTAINS(@j, '{"a": 1}') |
61+
+-------------------------------+
62+
| 1 |
63+
+-------------------------------+
64+
```
65+
2. NULL parameters
66+
```sql
67+
SELECT JSON_CONTAINS(NULL, '{"a": 1}');
68+
```
69+
```text
70+
+---------------------------------+
71+
| JSON_CONTAINS(NULL, '{"a": 1}') |
72+
+---------------------------------+
73+
| NULL |
74+
+---------------------------------+
75+
```
76+
```sql
77+
SELECT JSON_CONTAINS('{"a": 1}', NULL);
78+
```
79+
```text
80+
+---------------------------------+
81+
| JSON_CONTAINS('{"a": 1}', NULL) |
82+
+---------------------------------+
83+
| NULL |
84+
+---------------------------------+
85+
```
86+
```sql
87+
SELECT JSON_CONTAINS('{"a": 1}', '{"a": 1}', NULL);
88+
```
89+
```text
90+
+---------------------------------------------+
91+
| JSON_CONTAINS('{"a": 1}', '{"a": 1}', NULL) |
92+
+---------------------------------------------+
93+
| NULL |
94+
+---------------------------------------------+
95+
```

‎docs/sql-manual/sql-functions/scalar-functions/json-functions/json-exists-path.md

Lines changed: 50 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -7,57 +7,64 @@
77

88
## Description
99

10-
It is used to judge whether the field specified by json_path exists in the JSON data. If it exists, it returns TRUE, and if it does not exist, it returns FALSE
10+
Used to determine whether the field specified by `<path>` exists in JSON data. Returns TRUE if it exists, FALSE if it does not exist.
1111

1212
## Syntax
1313

1414
```sql
15-
JSON_EXISTS_PATH (<json_str>, <path>)
15+
JSON_EXISTS_PATH (<json_object>, <path>)
1616
```
1717

18-
## Alias
19-
20-
* JSONB_EXISTS_PATH
21-
2218
## Parameters
23-
| Parameter | Description |
24-
|--------------|--------------------------------------------------------|
25-
| `<json_str>` | The element to be included in the JSON array. It can be a value of any type, including NULL. If no element is specified, an empty array is returned.
26-
| `<path>` | The JSON path to be judged. If it is NULL, then return NULL. |
19+
- `<json_object>` JSON type, determine whether the path specified by `<path>` exists in it.
20+
- `<path>` String type, specifies the path.
2721

28-
## Return Values
29-
If it exists, return TRUE; if it does not exist, return FALSE.
22+
## Return Value
23+
- BOOL type, returns TRUE if it exists, FALSE if it does not exist
24+
- NULL: If either `<json_object>` or `<path>` is NULL, returns NULL.
3025

3126
## Examples
32-
33-
```sql
34-
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.name');
35-
```
36-
```text
37-
+---------------------------------------------------------------------------+
38-
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
39-
+---------------------------------------------------------------------------+
40-
| 1 |
41-
+---------------------------------------------------------------------------+
42-
```
43-
```sql
44-
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age');
45-
```
46-
```text
47-
+--------------------------------------------------------------------------+
48-
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.age') |
49-
+--------------------------------------------------------------------------+
50-
| 0 |
51-
+--------------------------------------------------------------------------+
52-
```
53-
```sql
54-
SELECT JSONB_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age');
55-
```
56-
```text
57-
+--------------------------------------------------------------------------+
58-
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.age') |
59-
+--------------------------------------------------------------------------+
60-
| 0 |
61-
+--------------------------------------------------------------------------+
62-
```
27+
1. Example 1
28+
```sql
29+
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.name');
30+
```
31+
```text
32+
+------------------------------------------------------------+
33+
| JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.name') |
34+
+------------------------------------------------------------+
35+
| 1 |
36+
+------------------------------------------------------------+
37+
```
38+
2. Example 2
39+
```sql
40+
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age');
41+
```
42+
```text
43+
+-----------------------------------------------------------+
44+
| JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age') |
45+
+-----------------------------------------------------------+
46+
| 0 |
47+
+-----------------------------------------------------------+
48+
```
49+
3. NULL parameters
50+
```sql
51+
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', NULL);
52+
```
53+
```text
54+
+--------------------------------------------------------+
55+
| JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', NULL) |
56+
+--------------------------------------------------------+
57+
| NULL |
58+
+--------------------------------------------------------+
59+
```
60+
```sql
61+
SELECT JSON_EXISTS_PATH(NULL, '$.age');
62+
```
63+
```text
64+
+---------------------------------+
65+
| JSON_EXISTS_PATH(NULL, '$.age') |
66+
+---------------------------------+
67+
| NULL |
68+
+---------------------------------+
69+
```
6370

‎docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-largeint.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ JSON_EXTRACT_LARGEINT(<json_object>, <json_path>)
3434
```sql
3535
SELECT json_extract_largeint('{"id": 11529215046068469760, "name": "doris"}', '$.id');
3636
```
37+
```text
3738
+--------------------------------------------------------------------------------+
3839
| json_extract_largeint('{"id": 11529215046068469760, "name": "doris"}', '$.id') |
3940
+--------------------------------------------------------------------------------+

‎docs/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ JSON_INSERT (<json_object>, <path>, <value>[, <path>, <value>, ...])
1919
- `<value>`: JSON type or other types supported by [`TO_JSON`](./to-json.md), the value to be inserted.
2020

2121
## Return Value
22-
- Nullable(JSON) Returns the modified JSON object
22+
- `Nullable(JSON)` Returns the modified JSON object
2323

2424
## Usage Notes
2525
1. Note that path-value pairs are evaluated from left to right.

0 commit comments

Comments
 (0)