Skip to content

Commit 1083816

Browse files
mrhhsgmrhhsg
authored
update json_parse (#2638)
## Versions - [x] dev - [ ] 3.0 - [ ] 2.1 - [ ] 2.0 ## Languages - [x] Chinese - [x] English
1 parent e75595c commit 1083816

File tree

2 files changed

+264
-220
lines changed
  • docs/sql-manual/sql-functions/scalar-functions/json-functions
  • i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions

2 files changed

+264
-220
lines changed

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

Lines changed: 135 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -6,131 +6,154 @@
66
---
77

88
## Description
9-
Parse the original JSON string into JSON binary format. To meet the needs of different abnormal data processing, different JSON_PARSE series functions are provided as follows:
10-
* JSON_PARSE: Parse the JSON string, and report an error when the input string is not a valid JSON string.
11-
* JSON_PARSE_ERROR_TO_INVALID: Parse the JSON string, and return NULL when the input string is not a valid JSON string.
12-
* JSON_PARSE_ERROR_TO_NULL: Parse the JSON string, and return NULL when the input string is not a valid JSON string.
13-
* JSON_PARSE_ERROR_TO_VALUE: Parse the JSON string, and return the default value specified by the parameter default_json_str when the input string is not a valid JSON string.
14-
* JSON_PARSE_NOTNULL: Parse the JSON string, and return NULL when the input string is not a valid JSON string.
15-
16-
## Alias
17-
* JSONB_PARSE is the same as JSON_PARSE
18-
* JSONB_PARSE_ERROR_TO_INVALID is the same as JSON_PARSE_ERROR_TO_INVALID
19-
* JSONB_PARSE_ERROR_TO_NULL is the same as JSON_PARSE_ERROR_TO_NULL
20-
* JSONB_PARSE_ERROR_TO_VALUE is the same as JSON_PARSE_ERROR_TO_VALUE
21-
* JSONB_PARSE_NOTNULL is the same as JSON_PARSE_NOTNULL
9+
Parse raw JSON strings into JSON binary format. To meet different exception data processing requirements, different JSON_PARSE series functions are provided, as follows:
10+
* `JSON_PARSE` Parse JSON strings. When the input string is not a valid JSON string, an error is reported.
11+
* `JSON_PARSE_ERROR_TO_NULL` Parse JSON strings. When the input string is not a valid JSON string, return NULL.
12+
* `JSON_PARSE_ERROR_TO_VALUE` Parse JSON strings. When the input string is not a valid JSON string, return the default value specified by the parameter default_json_value.
2213

2314
## Syntax
2415

2516
```sql
2617
JSON_PARSE (<json_str>)
2718
```
2819
```sql
29-
JSON_PARSE_ERROR_TO_INVALID (<json_str>)
30-
```
31-
```sql
3220
JSON_PARSE_ERROR_TO_NULL (<json_str>)
3321
```
3422

3523
```sql
36-
JSON_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_str>)
37-
```
38-
```sql
39-
JSONB_PARSE_NOTNULL (<json_str>)
24+
JSON_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_value>)
4025
```
4126

4227
## Parameters
43-
| Parameter | Description |
44-
|--------------|-----------------------------|
45-
| `<json_str>` | The JSON type parameter or field to be extracted. |
46-
| `<default_json_str>` | When the input string is not a valid JSON string, return the default value specified by the parameter default_json_str. | |
28+
### Required Parameters
29+
- `<json_str>` String type, whose content should be a valid JSON string.
30+
### Optional Parameters
31+
- `<default_json_value>` JSON type, can be NULL. When `<json_str>` parsing fails, `<default_json_value>` is returned as the default value.
4732

48-
## Return Values
49-
json_parse functions parse JSON string to binary format. A series of functions are provided to satisfy different demand for exception handling.
50-
- all return NULL if json_str is NULL
51-
- if json_str is not valid
52-
- json_parse will report error
53-
- json_parse_error_to_invalid will return NULL
54-
- json_parse_error_to_null will return NULL
55-
- json_parse_error_to_value will return the value specified by default_json_str
56-
- json_parse_notnull will return NULL
33+
## Return Value
34+
`Nullable<JSON>` Returns the parsed JSON object.
5735

58-
### Examples
59-
1. Parse valid JSON string
60-
```sql
61-
SELECT json_parse('{"k1":"v31","k2":300}');
62-
```
63-
```text
64-
+--------------------------------------+
65-
| json_parse('{"k1":"v31","k2":300}') |
66-
+--------------------------------------+
67-
| {"k1":"v31","k2":300} |
68-
+--------------------------------------+
69-
```
70-
```sql
71-
SELECT json_parse_error_to_invalid('{"k1":"v31","k2":300}');
72-
```
73-
```text
74-
+-------------------------------------------------------+
75-
| jsonb_parse_error_to_invalid('{"k1":"v31","k2":300}') |
76-
+-------------------------------------------------------+
77-
| {"k1":"v31","k2":300} |
78-
+-------------------------------------------------------+
79-
```
80-
```sql
81-
SELECT json_parse_notnull('{"a":"b"}');
82-
```
83-
```text
84-
+----------------------------------+
85-
| jsonb_parse_notnull('{"a":"b"}') |
86-
+----------------------------------+
87-
| {"a":"b"} |
88-
+----------------------------------+
89-
```
90-
```sql
91-
SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
92-
```
93-
```text
94-
+-----------------------------------------------------------+
95-
| jsonb_parse_error_to_value('{"k1":"v31","k2":300}', '{}') |
96-
+-----------------------------------------------------------+
97-
| {"k1":"v31","k2":300} |
98-
+-----------------------------------------------------------+
99-
```
100-
2. Parse invalid JSON string
101-
```sql
102-
SELECT json_parse('invalid json');
103-
```
104-
```text
105-
ERROR 1105 (HY000): errCode = 2, detailMessage = json parse error: Invalid document: document must be an object or an array for value: invalid json
106-
```
107-
```sql
108-
SELECT json_parse_error_to_invalid('invalid json');
109-
```
110-
```text
111-
+----------------------------------------------+
112-
| jsonb_parse_error_to_invalid('invalid json') |
113-
+----------------------------------------------+
114-
| NULL |
115-
+----------------------------------------------+
116-
```
117-
```sql
118-
SELECT json_parse_notnull('invalid json');
119-
```
120-
```text
121-
+-------------------------------------------+
122-
| jsonb_parse_error_to_null('invalid json') |
123-
+-------------------------------------------+
124-
| NULL |
125-
+-------------------------------------------+
126-
```
127-
```sql
128-
SELECT json_parse_error_to_value('invalid json', '{}');
129-
```
130-
```text
131-
+--------------------------------------------------+
132-
| json_parse_error_to_value('invalid json', '{}') |
133-
+--------------------------------------------------+
134-
| {} |
135-
+--------------------------------------------------+
136-
```
36+
## Usage Notes
37+
1. If `<json_str>` is NULL, the result is also NULL.
38+
2. `JSONB_PARSE`/`JSONB_PARSE_ERROR_TO_NULL`/`JSONB_PARSE_ERROR_TO_VALUE` have basically the same behavior, except that the results obtained when parsing fails are different.
39+
40+
## Examples
41+
1. Normal JSON string parsing
42+
```sql
43+
SELECT json_parse('{"k1":"v31","k2":300}');
44+
```
45+
```text
46+
+-------------------------------------+
47+
| json_parse('{"k1":"v31","k2":300}') |
48+
+-------------------------------------+
49+
| {"k1":"v31","k2":300} |
50+
+-------------------------------------+
51+
```
52+
```sql
53+
SELECT json_parse_error_to_null('{"k1":"v31","k2":300}','{}');
54+
```
55+
```text
56+
+---------------------------------------------------+
57+
| json_parse_error_to_null('{"k1":"v31","k2":300}') |
58+
+---------------------------------------------------+
59+
| {"k1":"v31","k2":300} |
60+
+---------------------------------------------------+
61+
```
62+
```sql
63+
SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
64+
```
65+
```text
66+
+---------------------------------------------------------+
67+
| json_parse_error_to_value('{"k1":"v31","k2":300}','{}') |
68+
+---------------------------------------------------------+
69+
| {"k1":"v31","k2":300} |
70+
+---------------------------------------------------------+
71+
```
72+
```sql
73+
SELECT json_parse_error_to_value('{"k1":"v31","k2":300}', NULL);
74+
```
75+
```text
76+
+----------------------------------------------------------+
77+
| json_parse_error_to_value('{"k1":"v31","k2":300}', NULL) |
78+
+----------------------------------------------------------+
79+
| {"k1":"v31","k2":300} |
80+
+----------------------------------------------------------+
81+
```
82+
2. Invalid JSON string parsing
83+
```sql
84+
SELECT json_parse('invalid json');
85+
```
86+
```text
87+
ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]Parse json document failed at row 0, error: [INTERNAL_ERROR]simdjson parse exception:
88+
```
89+
```sql
90+
SELECT json_parse_error_to_null('invalid json');
91+
```
92+
```text
93+
+------------------------------------------+
94+
| json_parse_error_to_null('invalid json') |
95+
+------------------------------------------+
96+
| NULL |
97+
+------------------------------------------+
98+
```
99+
```sql
100+
SELECT json_parse_error_to_value('invalid json');
101+
```
102+
```text
103+
+-------------------------------------------+
104+
| json_parse_error_to_value('invalid json') |
105+
+-------------------------------------------+
106+
| {} |
107+
+-------------------------------------------+
108+
```
109+
```sql
110+
SELECT json_parse_error_to_value('invalid json', '{"key": "default value"}');
111+
```
112+
```text
113+
+-----------------------------------------------------------------------+
114+
| json_parse_error_to_value('invalid json', '{"key": "default value"}') |
115+
+-----------------------------------------------------------------------+
116+
| {"key":"default value"} |
117+
+-----------------------------------------------------------------------+
118+
```
119+
```sql
120+
SELECT json_parse_error_to_value('invalid json', NULL);
121+
```
122+
```text
123+
+-------------------------------------------------+
124+
| json_parse_error_to_value('invalid json', NULL) |
125+
+-------------------------------------------------+
126+
| NULL |
127+
+-------------------------------------------------+
128+
```
129+
3. NULL parameters
130+
```sql
131+
SELECT json_parse(NULL);
132+
```
133+
```text
134+
+------------------+
135+
| json_parse(NULL) |
136+
+------------------+
137+
| NULL |
138+
+------------------+
139+
```
140+
```sql
141+
SELECT json_parse_error_to_null(NULL);
142+
```
143+
```text
144+
+--------------------------------+
145+
| json_parse_error_to_null(NULL) |
146+
+--------------------------------+
147+
| NULL |
148+
+--------------------------------+
149+
```
150+
```sql
151+
SELECT json_parse_error_to_value(NULL, '{}');
152+
```
153+
```text
154+
+---------------------------------------+
155+
| json_parse_error_to_value(NULL, '{}') |
156+
+---------------------------------------+
157+
| NULL |
158+
+---------------------------------------+
159+
```

0 commit comments

Comments
 (0)