Skip to content

Commit 9317050

Browse files
mklzlyuanyuan8983
mklzl
authored and
yuanyuan8983
committed
[doc] Fix json_fun_* en_doc (apache#1862)
"json_array json_object json_quote json_unquote json_extract json_insert json_replace json_set json_exists_path jsonb_extract json_parse " ## Versions - [x] dev - [x] 3.0 - [x] 2.1 - [ ] 2.0 ## Languages - [ ] Chinese - [x] English ## Docs Checklist - [ ] Checked by AI - [ ] Test Cases Built
1 parent cbd393f commit 9317050

34 files changed

+1668
-682
lines changed

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

+37-13
Original file line numberDiff line numberDiff line change
@@ -24,47 +24,71 @@ specific language governing permissions and limitations
2424
under the License.
2525
-->
2626

27-
## json_array
28-
### Description
29-
#### Syntax
27+
## Description
28+
Generate a json array containing the specified values, return empty if no values
29+
3030

31-
`VARCHAR json_array(VARCHAR,...)`
31+
## Syntax
32+
```sql
33+
JSON_ARRAY (<a>, ...)
34+
```
3235

36+
## Parameters
37+
| Parameter | Description |
38+
|------|---------------------------------------------------------------------------------------------------------------|
39+
| `<a>, ...` | Elements to be included in the JSON array. It can be a single or multiple values of any type, including NULL. |
3340

34-
Generate a json array containing the specified values, return empty if no values
3541

36-
### example
42+
## Return Values
43+
Returns a JSON array containing the specified values. If no values are specified, an empty JSON array is returned.
3744

45+
46+
## Examples
47+
48+
```sql
49+
select json_array();
3850
```
39-
MySQL> select json_array();
51+
52+
```text
4053
+--------------+
4154
| json_array() |
4255
+--------------+
4356
| [] |
4457
+--------------+
58+
```
4559

46-
MySQL> select json_array(null);
60+
```sql
61+
select json_array(null);
62+
```
63+
64+
```text
4765
+--------------------+
4866
| json_array('NULL') |
4967
+--------------------+
5068
| [NULL] |
5169
+--------------------+
70+
```
71+
```sql
72+
SELECT json_array(1, "abc", NULL, TRUE, CURTIME());
73+
```
5274

53-
54-
MySQL> SELECT json_array(1, "abc", NULL, TRUE, CURTIME());
75+
```text
5576
+-----------------------------------------------+
5677
| json_array(1, 'abc', 'NULL', TRUE, curtime()) |
5778
+-----------------------------------------------+
5879
| [1, "abc", NULL, TRUE, "10:41:15"] |
5980
+-----------------------------------------------+
81+
```
6082

83+
```sql
84+
select json_array("a", null, "c");
85+
```
6186

62-
MySQL> select json_array("a", null, "c");
87+
```text
6388
+------------------------------+
6489
| json_array('a', 'NULL', 'c') |
6590
+------------------------------+
6691
| ["a", NULL, "c"] |
6792
+------------------------------+
6893
```
69-
### keywords
70-
json,array,json_array
94+

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

+46-8
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
---
23
{
34
"title": "JSON_EXISTS_PATH",
@@ -24,23 +25,60 @@ specific language governing permissions and limitations
2425
under the License.
2526
-->
2627

27-
## json_exists_path
2828

29-
### description
29+
## Description
3030

3131
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
3232

33-
#### Syntax
33+
## Syntax
3434

3535
```sql
36-
BOOLEAN json_exists_path(JSON j, VARCHAR json_path)
36+
JSON_EXISTS_PATH (<json_str>, <path>)
3737
```
3838

39-
### example
39+
## Alias
40+
41+
* JSONB_EXISTS_PATH
42+
43+
## Parameters
44+
| Parameter | Description |
45+
|--------------|--------------------------------------------------------|
46+
| `<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.
47+
| `<path>` | The JSON path to be judged. If it is NULL, then return NULL. |
4048

41-
Refer to [json tutorial](../../sql-reference/Data-Types/JSON.md)
49+
## Return Values
50+
If it exists, return TRUE; if it does not exist, return FALSE.
4251

43-
### keywords
52+
## Examples
4453

45-
json_exists_path
54+
```sql
55+
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.name');
56+
```
57+
```text
58+
+---------------------------------------------------------------------------+
59+
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
60+
+---------------------------------------------------------------------------+
61+
| 1 |
62+
+---------------------------------------------------------------------------+
63+
```
64+
```sql
65+
SELECT JSON_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age');
66+
```
67+
```text
68+
+--------------------------------------------------------------------------+
69+
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.age') |
70+
+--------------------------------------------------------------------------+
71+
| 0 |
72+
+--------------------------------------------------------------------------+
73+
```
74+
```sql
75+
SELECT JSONB_EXISTS_PATH('{"id": 123, "name": "doris"}', '$.age');
76+
```
77+
```text
78+
+--------------------------------------------------------------------------+
79+
| jsonb_exists_path(cast('{"id": 123, "name": "doris"}' as JSON), '$.age') |
80+
+--------------------------------------------------------------------------+
81+
| 0 |
82+
+--------------------------------------------------------------------------+
83+
```
4684

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

+124-68
Original file line numberDiff line numberDiff line change
@@ -24,109 +24,165 @@ specific language governing permissions and limitations
2424
under the License.
2525
-->
2626

27-
## json_extract
28-
29-
### description
30-
31-
#### Syntax
3227

28+
## Description
29+
JSON_EXTRACT is a series of functions that extract the field specified by json_path from JSON data and provide different series of functions according to the type of the field to be extracted.
30+
31+
* JSON_EXTRACT returns the VARCHAR type for a json string of the VARCHAR type.
32+
* JSON_EXTRACT_ISNULL returns the BOOLEAN type indicating whether it is a json null.
33+
* JSON_EXTRACT_BOOL returns the BOOLEAN type.
34+
* JSON_EXTRACT_INT returns the INT type.
35+
* JSON_EXTRACT_BIGINT returns the BIGINT type.
36+
* JSON_EXTRACT_LARGEINT returns the LARGEINT type.
37+
* JSON_EXTRACT_DOUBLE returns the DOUBLE type.
38+
* JSON_EXTRACT_STRING returns the STRING type.
39+
40+
## Alias
41+
* JSONB_EXTRACT is the same as JSON_EXTRACT.
42+
* JSONB_EXTRACT_ISNULL is the same as JSON_EXTRACT_ISNULL.
43+
* JSONB_EXTRACT_BOOL is the same as JSON_EXTRACT_BOOL.
44+
* JSONB_EXTRACT_INT is the same as JSON_EXTRACT_INT.
45+
* JSONB_EXTRACT_BIGINT is the same as JSON_EXTRACT_BIGINT.
46+
* JSONB_EXTRACT_LARGEINT is the same as JSON_EXTRACT_LARGEINT.
47+
* JSONB_EXTRACT_DOUBLE is the same as JSON_EXTRACT_DOUBLE.
48+
* JSONB_EXTRACT_STRING is the same as JSON_EXTRACT_STRING.
49+
50+
## Syntax
3351
```sql
34-
`VARCHAR json_extract(VARCHAR json_str, VARCHAR path[, VARCHAR path] ...))`
35-
JSON jsonb_extract(JSON j, VARCHAR json_path)
36-
BOOLEAN json_extract_isnull(JSON j, VARCHAR json_path)
37-
BOOLEAN json_extract_bool(JSON j, VARCHAR json_path)
38-
INT json_extract_int(JSON j, VARCHAR json_path)
39-
BIGINT json_extract_bigint(JSON j, VARCHAR json_path)
40-
LARGEINT json_extract_largeint(JSON j, VARCHAR json_path)
41-
DOUBLE json_extract_double(JSON j, VARCHAR json_path)
42-
STRING json_extract_string(JSON j, VARCHAR json_path)
52+
JSON_EXTRACT (<json_str>, <path>[, path] ...)
4353
```
54+
```sql
55+
JSON_EXTRACT_ISNULL (<json_str>, <path>)
56+
```
57+
```sql
58+
JSON_EXTRACT_BOOL (<json_str>, <path>)
59+
```
60+
```sql
61+
JSON_EXTRACT_INT (<json_str>, <path>)
62+
```
63+
```sql
64+
JSON_EXTRACT_BIGINT (<json_str>, <path>)
65+
```
66+
```sql
67+
JSON_EXTRACT_LARGEINT (<json_str>, <path>)
68+
```
69+
```sql
70+
JSON_EXTRACT_DOUBLE (<json_str>, <path>)
71+
```
72+
```sql
73+
JSON_EXTRACT_STRING (<json_str>, <path>)
74+
```
75+
Alias functions have the same syntax and usage as the above functions, except for the function names.
4476

45-
json_extract functions extract field specified by json_path from JSON. A series of functions are provided for different datatype.
46-
- json_extract with VARCHAR argument, extract and return VARCHAR datatype
47-
- jsonb_extract extract and return JSON datatype
48-
- json_extract_isnull check if the field is json null and return BOOLEAN datatype
49-
- json_extract_bool extract and return BOOLEAN datatype
50-
- json_extract_int extract and return INT datatype
51-
- json_extract_bigint extract and return BIGINT datatype
52-
- json_extract_largeint extract and return LARGEINT datatype
53-
- json_extract_double extract and return DOUBLE datatype
54-
- json_extract_STRING extract and return STRING datatype
55-
77+
## Parameters
78+
| Parameter | Description |
79+
|--------------|-----------------------------|
80+
| `<json_str>` | The JSON-type parameter or field to be extracted. |
81+
| `<path>` | The JSON path to extract the target element from the target JSON. |
5682
json path syntax:
5783
- '$' for json document root
5884
- '.k1' for element of json object with key 'k1'
5985
- If the key column value contains ".", double quotes are required in json_path, For example: SELECT json_extract('{"k1.a":"abc","k2":300}', '$."k1.a"');
6086
- '[i]' for element of json array at index i
6187
- Use '$[last]' to get the last element of json_array, and '$[last-1]' to get the penultimate element, and so on.
6288

89+
## Return Values
90+
According to the type of the field to be extracted, return the data type of the specified JSON_PATH in the target JSON. Special case handling is as follows:
91+
* If the field specified by json_path does not exist in the JSON, return NULL.
92+
* If the actual type of the field specified by json_path in the JSON is inconsistent with the type specified by json_extract_t.
93+
* if it can be losslessly converted to the specified type, return the specified type t; if not, return NULL.
6394

64-
Exception handling is as follows:
65-
- if the field specified by json_path does not exist, return NULL
66-
- if datatype of the field specified by json_path is not the same with type of json_extract_t, return t if it can be cast to t else NULL
6795

6896

69-
## json_exists_path and json_type
70-
### description
71-
72-
#### Syntax
73-
97+
## Examples
7498
```sql
75-
BOOLEAN json_exists_path(JSON j, VARCHAR json_path)
76-
STRING json_type(JSON j, VARCHAR json_path)
99+
SELECT json_extract('{"id": 123, "name": "doris"}', '$.id');
77100
```
78101

79-
There are two extra functions to check field existence and type
80-
- json_exists_path check the existence of the field specified by json_path, return TRUE or FALS
81-
- json_type get the type as follows of the field specified by json_path, return NULL if it does not exist
82-
- object
83-
- array
84-
- null
85-
- bool
86-
- int
87-
- bigint
88-
- largeint
89-
- double
90-
- string
91-
92-
### example
93-
94-
refer to [json tutorial](../../sql-reference/Data-Types/JSON.md) for more.
95-
96-
```
97-
mysql> SELECT json_extract('{"id": 123, "name": "doris"}', '$.id');
102+
```text
98103
+------------------------------------------------------+
99104
| json_extract('{"id": 123, "name": "doris"}', '$.id') |
100105
+------------------------------------------------------+
101106
| 123 |
102107
+------------------------------------------------------+
103-
1 row in set (0.01 sec)
104-
105-
mysql> SELECT json_extract('[1, 2, 3]', '$.[1]');
108+
```
109+
```sql
110+
SELECT json_extract('[1, 2, 3]', '$.[1]');
111+
```
112+
```text
106113
+------------------------------------+
107114
| json_extract('[1, 2, 3]', '$.[1]') |
108115
+------------------------------------+
109116
| 2 |
110117
+------------------------------------+
111-
1 row in set (0.01 sec)
112-
113-
mysql> SELECT json_extract('{"k1": "v1", "k2": { "k21": 6.6, "k22": [1, 2] } }', '$.k1', '$.k2.k21', '$.k2.k22', '$.k2.k22[1]');
118+
```
119+
```sql
120+
SELECT json_extract('{"k1": "v1", "k2": { "k21": 6.6, "k22": [1, 2] } }', '$.k1', '$.k2.k21', '$.k2.k22', '$.k2.k22[1]');
121+
```
122+
```text
114123
+-------------------------------------------------------------------------------------------------------------------+
115124
| json_extract('{"k1": "v1", "k2": { "k21": 6.6, "k22": [1, 2] } }', '$.k1', '$.k2.k21', '$.k2.k22', '$.k2.k22[1]') |
116125
+-------------------------------------------------------------------------------------------------------------------+
117126
| ["v1",6.6,[1,2],2] |
118127
+-------------------------------------------------------------------------------------------------------------------+
119-
1 row in set (0.01 sec)
120-
121-
mysql> SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
128+
```
129+
```sql
130+
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
131+
```
132+
```text
122133
+-----------------------------------------------------------------+
123134
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
124135
+-----------------------------------------------------------------+
125136
| [null,"doris"] |
126137
+-----------------------------------------------------------------+
127-
1 row in set (0.01 sec)
128138
```
129-
130-
131-
### keywords
132-
JSONB, JSON, json_extract, json_extract_isnull, json_extract_bool, json_extract_int, json_extract_bigint, json_extract_largeint,json_extract_double, json_extract_string, json_exists_path, json_type
139+
```sql
140+
SELECT JSON_EXTRACT_ISNULL('{"id": 123, "name": "doris"}', '$.id');
141+
```
142+
```text
143+
+----------------------------------------------------------------------------+
144+
| jsonb_extract_isnull(cast('{"id": 123, "name": "doris"}' as JSON), '$.id') |
145+
+----------------------------------------------------------------------------+
146+
| 0 |
147+
+----------------------------------------------------------------------------+
148+
```
149+
```sql
150+
SELECT JSON_EXTRACT_BOOL('{"id": 123, "name": "NULL"}', '$.id');
151+
```
152+
```text
153+
+-------------------------------------------------------------------------+
154+
| jsonb_extract_bool(cast('{"id": 123, "name": "NULL"}' as JSON), '$.id') |
155+
+-------------------------------------------------------------------------+
156+
| NULL |
157+
+-------------------------------------------------------------------------+
158+
```
159+
```sql
160+
SELECT JSON_EXTRACT_INT('{"id": 123, "name": "NULL"}', '$.id');
161+
```
162+
```text
163+
+------------------------------------------------------------------------+
164+
| jsonb_extract_int(cast('{"id": 123, "name": "NULL"}' as JSON), '$.id') |
165+
+------------------------------------------------------------------------+
166+
| 123 |
167+
+------------------------------------------------------------------------+
168+
```
169+
```sql
170+
SELECT JSON_EXTRACT_INT('{"id": 123, "name": "doris"}', '$.name');
171+
```
172+
```text
173+
+---------------------------------------------------------------------------+
174+
| jsonb_extract_int(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
175+
+---------------------------------------------------------------------------+
176+
| NULL |
177+
+---------------------------------------------------------------------------+
178+
```
179+
```sql
180+
SELECT JSON_EXTRACT_STRING('{"id": 123, "name": "doris"}', '$.name');
181+
```
182+
```text
183+
+------------------------------------------------------------------------------+
184+
| jsonb_extract_string(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
185+
+------------------------------------------------------------------------------+
186+
| doris |
187+
+------------------------------------------------------------------------------+
188+
```

0 commit comments

Comments
 (0)