Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Merge json_parse_* docs into json_parse zh_doc #1846

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

[doc] Merge json_parse_* docs into json_parse zh_doc #1846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
610d09b
[doc] Merge json_parse_* docs into json_parse zh_doc
mklzl Jan 17, 2025
d02e03e
[doc] Fix syntax format for json_parse zh_doc
mklzl Jan 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 104 additions & 30 deletions .../current/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,60 +24,134 @@ specific language governing permissions and limitations
under the License.
-->

## json_parse
## 描述
将原始 JSON 字符串解析成 JSON 二进制格式。为了满足不同的异常数据处理需求，提供不同的 JSON_PARSE 系列函数，具体如下：
* JSON_PARSE 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，报错。
* JSON_PARSE_ERROR_TO_INVALID 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。
* JSON_PARSE_ERROR_TO_NULL 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。
* JSON_PARSE_ERROR_TO_VALUE 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回参数 default_json_str 指定的默认值。
* JSON_PARSE_NOTNULL 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。

## 别名
* JSONB_PARSE 同 `JSON_PARSE`
* JSONB_PARSE_ERROR_TO_INVALID 同 `JSON_PARSE_ERROR_TO_INVALID`
* JSONB_PARSE_ERROR_TO_NULL 同 `JSON_PARSE_ERROR_TO_NULL`
* JSONB_PARSE_ERROR_TO_VALUE 同 `JSON_PARSE_ERROR_TO_VALUE`
* JSONB_PARSE_NOTNULL 同 `JSON_PARSE_NOTNULL`

## 语法

```sql
JSON json_parse(VARCHAR json_str)
JSON json_parse_error_to_null(VARCHAR json_str)
JSON json_parse_error_to_value(VARCHAR json_str, VARCHAR default_json_str)
JSON_PARSE (<json_str>)
```
```sql
JSON_PARSE_ERROR_TO_INVALID (<json_str>)
```
```sql
JSON_PARSE_ERROR_TO_NULL (<json_str>)
```

```sql
JSON_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_str>)
```
```sql
JSONB_PARSE_NOTNULL (<json_str>)
```

将原始JSON字符串解析成JSON二进制格式。为了满足不同的异常数据处理需求，提供不同的json_parse系列函数，具体行为如下：
- json_str为NULL时，都返回NULL
- json_str为非法JSON字符串时
- json_parse报错
- json_parse_error_to_null返回NULL，
- json_parse_error_to_value返回参数default_json_str指定的默认值
## 参数
| 参数 | 描述 |
|--------------|-----------------------------|
| `<json_str>` | 要提取的 JSON 类型的参数或者字段 |
| `<default_json_str>` | 当输入的字符串不是合法的 JSON 字符串时，返回参数 default_json_str 指定的默认值。 |

## 返回值
* json_str 为 NULL 时，都返回 NULL
* json_str 为非法 JSON 字符串时
- JSON_PARSE 报错
- JSON_PARSE_ERROR_TO_INVALID 返回 NULL
- JSON_PARSE_ERROR_TO_NULL 返回 NULL
- JSON_PARSE_ERROR_TO_VALUE 返回参数 default_json_str 指定的默认值
- JSON_PARSE_NOTNULL 返回 NULL


## 举例

1. 正常JSON字符串解析
## 示例

1. 正常 JSON 字符串解析
```sql
SELECT json_parse('{"k1":"v31","k2":300}');
```
mysql> SELECT json_parse('{"k1":"v31","k2":300}');
```text
+--------------------------------------+
| json_parse('{"k1":"v31","k2":300}') |
+--------------------------------------+
| {"k1":"v31","k2":300} |
+--------------------------------------+
1 row in set (0.01 sec)
```

2. 非法JSON字符串解析

```sql
SELECT json_parse_error_to_invalid('{"k1":"v31","k2":300}');
```
```text
+-------------------------------------------------------+
| jsonb_parse_error_to_invalid('{"k1":"v31","k2":300}') |
+-------------------------------------------------------+
| {"k1":"v31","k2":300} |
+-------------------------------------------------------+
```
```sql
SELECT json_parse_notnull('{"a":"b"}');
```
mysql> SELECT json_parse('invalid json');
```text
+----------------------------------+
| jsonb_parse_notnull('{"a":"b"}') |
+----------------------------------+
| {"a":"b"} |
+----------------------------------+
```
```sql
SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
```
```text
+-----------------------------------------------------------+
| jsonb_parse_error_to_value('{"k1":"v31","k2":300}', '{}') |
+-----------------------------------------------------------+
| {"k1":"v31","k2":300} |
+-----------------------------------------------------------+
```
2. 非法 JSON 字符串解析
```sql
SELECT json_parse('invalid json');
```
```text
ERROR 1105 (HY000): errCode = 2, detailMessage = json parse error: Invalid document: document must be an object or an array for value: invalid json

mysql> SELECT json_parse_error_to_null('invalid json');
```
```sql
SELECT json_parse_error_to_invalid('invalid json');
```
```text
+----------------------------------------------+
| jsonb_parse_error_to_invalid('invalid json') |
+----------------------------------------------+
| NULL |
+----------------------------------------------+
```
```sql
SELECT json_parse_notnull('invalid json');
```
```text
+-------------------------------------------+
| json_parse_error_to_null('invalid json') |
| jsonb_parse_error_to_null('invalid json') |
+-------------------------------------------+
| NULL |
+-------------------------------------------+
1 row in set (0.01 sec)

mysql> SELECT json_parse_error_to_value('invalid json', '{}');
```
```sql
SELECT json_parse_error_to_value('invalid json', '{}');
```
```text
+--------------------------------------------------+
| json_parse_error_to_value('invalid json', '{}') |
+--------------------------------------------------+
| {} |
+--------------------------------------------------+
1 row in set (0.00 sec)
```


### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value
```
134 changes: 104 additions & 30 deletions ...sion-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,60 +24,134 @@ specific language governing permissions and limitations
under the License.
-->

## json_parse
## 描述
将原始 JSON 字符串解析成 JSON 二进制格式。为了满足不同的异常数据处理需求，提供不同的 JSON_PARSE 系列函数，具体如下：
* JSON_PARSE 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，报错。
* JSON_PARSE_ERROR_TO_INVALID 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。
* JSON_PARSE_ERROR_TO_NULL 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。
* JSON_PARSE_ERROR_TO_VALUE 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回参数 default_json_str 指定的默认值。
* JSON_PARSE_NOTNULL 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。

## 别名
* JSONB_PARSE 同 `JSON_PARSE`
* JSONB_PARSE_ERROR_TO_INVALID 同 `JSON_PARSE_ERROR_TO_INVALID`
* JSONB_PARSE_ERROR_TO_NULL 同 `JSON_PARSE_ERROR_TO_NULL`
* JSONB_PARSE_ERROR_TO_VALUE 同 `JSON_PARSE_ERROR_TO_VALUE`
* JSONB_PARSE_NOTNULL 同 `JSON_PARSE_NOTNULL`

## 语法

```sql
JSON json_parse(VARCHAR json_str)
JSON json_parse_error_to_null(VARCHAR json_str)
JSON json_parse_error_to_value(VARCHAR json_str, VARCHAR default_json_str)
JSON_PARSE (<json_str>)
```
```sql
JSON_PARSE_ERROR_TO_INVALID (<json_str>)
```
```sql
JSON_PARSE_ERROR_TO_NULL (<json_str>)
```

```sql
JSON_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_str>)
```
```sql
JSONB_PARSE_NOTNULL (<json_str>)
```

将原始JSON字符串解析成JSON二进制格式。为了满足不同的异常数据处理需求，提供不同的json_parse系列函数，具体行为如下：
- json_str为NULL时，都返回NULL
- json_str为非法JSON字符串时
- json_parse报错
- json_parse_error_to_null返回NULL，
- json_parse_error_to_value返回参数default_json_str指定的默认值
## 参数
| 参数 | 描述 |
|--------------|-----------------------------|
| `<json_str>` | 要提取的 JSON 类型的参数或者字段 |
| `<default_json_str>` | 当输入的字符串不是合法的 JSON 字符串时，返回参数 default_json_str 指定的默认值。 |

## 返回值
* json_str 为 NULL 时，都返回 NULL
* json_str 为非法 JSON 字符串时
- JSON_PARSE 报错
- JSON_PARSE_ERROR_TO_INVALID 返回 NULL
- JSON_PARSE_ERROR_TO_NULL 返回 NULL
- JSON_PARSE_ERROR_TO_VALUE 返回参数 default_json_str 指定的默认值
- JSON_PARSE_NOTNULL 返回 NULL


## 举例

1. 正常JSON字符串解析
## 示例

1. 正常 JSON 字符串解析
```sql
SELECT json_parse('{"k1":"v31","k2":300}');
```
mysql> SELECT json_parse('{"k1":"v31","k2":300}');
```text
+--------------------------------------+
| json_parse('{"k1":"v31","k2":300}') |
+--------------------------------------+
| {"k1":"v31","k2":300} |
+--------------------------------------+
1 row in set (0.01 sec)
```

2. 非法JSON字符串解析

```sql
SELECT json_parse_error_to_invalid('{"k1":"v31","k2":300}');
```
```text
+-------------------------------------------------------+
| jsonb_parse_error_to_invalid('{"k1":"v31","k2":300}') |
+-------------------------------------------------------+
| {"k1":"v31","k2":300} |
+-------------------------------------------------------+
```
```sql
SELECT json_parse_notnull('{"a":"b"}');
```
mysql> SELECT json_parse('invalid json');
```text
+----------------------------------+
| jsonb_parse_notnull('{"a":"b"}') |
+----------------------------------+
| {"a":"b"} |
+----------------------------------+
```
```sql
SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
```
```text
+-----------------------------------------------------------+
| jsonb_parse_error_to_value('{"k1":"v31","k2":300}', '{}') |
+-----------------------------------------------------------+
| {"k1":"v31","k2":300} |
+-----------------------------------------------------------+
```
2. 非法 JSON 字符串解析
```sql
SELECT json_parse('invalid json');
```
```text
ERROR 1105 (HY000): errCode = 2, detailMessage = json parse error: Invalid document: document must be an object or an array for value: invalid json

mysql> SELECT json_parse_error_to_null('invalid json');
```
```sql
SELECT json_parse_error_to_invalid('invalid json');
```
```text
+----------------------------------------------+
| jsonb_parse_error_to_invalid('invalid json') |
+----------------------------------------------+
| NULL |
+----------------------------------------------+
```
```sql
SELECT json_parse_notnull('invalid json');
```
```text
+-------------------------------------------+
| json_parse_error_to_null('invalid json') |
| jsonb_parse_error_to_null('invalid json') |
+-------------------------------------------+
| NULL |
+-------------------------------------------+
1 row in set (0.01 sec)

mysql> SELECT json_parse_error_to_value('invalid json', '{}');
```
```sql
SELECT json_parse_error_to_value('invalid json', '{}');
```
```text
+--------------------------------------------------+
| json_parse_error_to_value('invalid json', '{}') |
+--------------------------------------------------+
| {} |
+--------------------------------------------------+
1 row in set (0.00 sec)
```


### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value
```
Loading