This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 10838161697 update json_parse (#2638)
10838161697 is described below
commit 10838161697b75be04a074904513601bf35d2be3
Author: Jerry Hu <[email protected]>
AuthorDate: Fri Jul 18 11:46:48 2025 +0800
update json_parse (#2638)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
---
.../scalar-functions/json-functions/json-parse.md | 247 +++++++++++----------
.../scalar-functions/json-functions/json-parse.md | 237 +++++++++++---------
2 files changed, 264 insertions(+), 220 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
index a6b27854844..03b7485092f 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
@@ -6,19 +6,10 @@
---
## Description
-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:
-* JSON_PARSE: Parse the JSON string, and report an error when the input string
is not a valid JSON string.
-* JSON_PARSE_ERROR_TO_INVALID: Parse the JSON string, and return NULL when the
input string is not a valid JSON string.
-* JSON_PARSE_ERROR_TO_NULL: Parse the JSON string, and return NULL when the
input string is not a valid JSON string.
-* 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.
-* JSON_PARSE_NOTNULL: Parse the JSON string, and return NULL when the input
string is not a valid JSON string.
-
-## Alias
-* JSONB_PARSE is the same as JSON_PARSE
-* JSONB_PARSE_ERROR_TO_INVALID is the same as JSON_PARSE_ERROR_TO_INVALID
-* JSONB_PARSE_ERROR_TO_NULL is the same as JSON_PARSE_ERROR_TO_NULL
-* JSONB_PARSE_ERROR_TO_VALUE is the same as JSON_PARSE_ERROR_TO_VALUE
-* JSONB_PARSE_NOTNULL is the same as JSON_PARSE_NOTNULL
+Parse raw JSON strings into JSON binary format. To meet different exception
data processing requirements, different JSON_PARSE series functions are
provided, as follows:
+* `JSON_PARSE` Parse JSON strings. When the input string is not a valid JSON
string, an error is reported.
+* `JSON_PARSE_ERROR_TO_NULL` Parse JSON strings. When the input string is not
a valid JSON string, return NULL.
+* `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.
## Syntax
@@ -26,111 +17,143 @@ Parse the original JSON string into JSON binary format.
To meet the needs of dif
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_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_value>)
```
## Parameters
-| Parameter | Description |
-|--------------|-----------------------------|
-| `<json_str>` | The JSON type parameter or field to be extracted. |
-| `<default_json_str>` | When the input string is not a valid JSON string,
return the default value specified by the parameter default_json_str. |
|
+### Required Parameters
+- `<json_str>` String type, whose content should be a valid JSON string.
+### Optional Parameters
+- `<default_json_value>` JSON type, can be NULL. When `<json_str>` parsing
fails, `<default_json_value>` is returned as the default value.
-## Return Values
-json_parse functions parse JSON string to binary format. A series of functions
are provided to satisfy different demand for exception handling.
-- all return NULL if json_str is NULL
-- if json_str is not valid
- - json_parse will report error
- - json_parse_error_to_invalid will return NULL
- - json_parse_error_to_null will return NULL
- - json_parse_error_to_value will return the value specified by
default_json_str
- - json_parse_notnull will return NULL
+## Return Value
+`Nullable<JSON>` Returns the parsed JSON object.
-### Examples
-1. Parse valid JSON string
-```sql
-SELECT json_parse('{"k1":"v31","k2":300}');
-```
-```text
-+--------------------------------------+
-| json_parse('{"k1":"v31","k2":300}') |
-+--------------------------------------+
-| {"k1":"v31","k2":300} |
-+--------------------------------------+
-```
-```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"}');
-```
-```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. Parse invalid JSON string
-```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
-```
-```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
-+-------------------------------------------+
-| jsonb_parse_error_to_null('invalid json') |
-+-------------------------------------------+
-| NULL |
-+-------------------------------------------+
-```
-```sql
-SELECT json_parse_error_to_value('invalid json', '{}');
-```
-```text
-+--------------------------------------------------+
-| json_parse_error_to_value('invalid json', '{}') |
-+--------------------------------------------------+
-| {} |
-+--------------------------------------------------+
-```
+## Usage Notes
+1. If `<json_str>` is NULL, the result is also NULL.
+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.
+
+## Examples
+1. Normal JSON string parsing
+ ```sql
+ SELECT json_parse('{"k1":"v31","k2":300}');
+ ```
+ ```text
+ +-------------------------------------+
+ | json_parse('{"k1":"v31","k2":300}') |
+ +-------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +-------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_null('{"k1":"v31","k2":300}','{}');
+ ```
+ ```text
+ +---------------------------------------------------+
+ | json_parse_error_to_null('{"k1":"v31","k2":300}') |
+ +---------------------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +---------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
+ ```
+ ```text
+ +---------------------------------------------------------+
+ | json_parse_error_to_value('{"k1":"v31","k2":300}','{}') |
+ +---------------------------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +---------------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('{"k1":"v31","k2":300}', NULL);
+ ```
+ ```text
+ +----------------------------------------------------------+
+ | json_parse_error_to_value('{"k1":"v31","k2":300}', NULL) |
+ +----------------------------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +----------------------------------------------------------+
+ ```
+2. Invalid JSON string parsing
+ ```sql
+ SELECT json_parse('invalid json');
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]Parse
json document failed at row 0, error: [INTERNAL_ERROR]simdjson parse exception:
+ ```
+ ```sql
+ SELECT json_parse_error_to_null('invalid json');
+ ```
+ ```text
+ +------------------------------------------+
+ | json_parse_error_to_null('invalid json') |
+ +------------------------------------------+
+ | NULL |
+ +------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json');
+ ```
+ ```text
+ +-------------------------------------------+
+ | json_parse_error_to_value('invalid json') |
+ +-------------------------------------------+
+ | {} |
+ +-------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json', '{"key": "default
value"}');
+ ```
+ ```text
+ +-----------------------------------------------------------------------+
+ | json_parse_error_to_value('invalid json', '{"key": "default value"}') |
+ +-----------------------------------------------------------------------+
+ | {"key":"default value"} |
+ +-----------------------------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json', NULL);
+ ```
+ ```text
+ +-------------------------------------------------+
+ | json_parse_error_to_value('invalid json', NULL) |
+ +-------------------------------------------------+
+ | NULL |
+ +-------------------------------------------------+
+ ```
+3. NULL parameters
+ ```sql
+ SELECT json_parse(NULL);
+ ```
+ ```text
+ +------------------+
+ | json_parse(NULL) |
+ +------------------+
+ | NULL |
+ +------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_null(NULL);
+ ```
+ ```text
+ +--------------------------------+
+ | json_parse_error_to_null(NULL) |
+ +--------------------------------+
+ | NULL |
+ +--------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value(NULL, '{}');
+ ```
+ ```text
+ +---------------------------------------+
+ | json_parse_error_to_value(NULL, '{}') |
+ +---------------------------------------+
+ | NULL |
+ +---------------------------------------+
+ ```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
index 95f0dd1c594..0fd7ca88d45 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-parse.md
@@ -7,18 +7,9 @@
## 描述
将原始 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`
+* `JSON_PARSE` 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，报错。
+* `JSON_PARSE_ERROR_TO_NULL` 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回 NULL。
+* `JSON_PARSE_ERROR_TO_VALUE` 解析 JSON 字符串，当输入的字符串不是合法的 JSON 字符串时，返回参数
default_json_value 指定的默认值。
## 语法
@@ -26,113 +17,143 @@
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_PARSE_ERROR_TO_VALUE (<json_str>, <default_json_value>)
```
## 参数
-| 参数 | 描述 |
-|--------------|-----------------------------|
-| `<json_str>` | 要提取的 JSON 类型的参数或者字段 |
-| `<default_json_str>` | 当输入的字符串不是合法的 JSON 字符串时，返回参数 default_json_str
指定的默认值。 |
+### 必须参数
+- `<json_str>` String 类型，其内容应是合法的 JSON 字符串。
+### 可选参数
+- `<default_json_value>` JSON 类型，可以是 NULL，当 `<json_str>`
解析失败时，`<default_json_value>` 作为默认值返回。
## 返回值
-* 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
-
+`Nullable<JSON>` 返回解析后得到的 JSON 对象
+## 使用说明
+1. 如果 `<json_str>` 是 NULL，得到的结果也是 NULL。
+2. `JSONB_PARSE`/`JSONB_PARSE_ERROR_TO_NULL`/`JSONB_PARSE_ERROR_TO_VALUE`
行为基本一致，只是在解析失败时得到的结果不同。
## 示例
-
1. 正常 JSON 字符串解析
-```sql
-SELECT json_parse('{"k1":"v31","k2":300}');
-```
-```text
-+--------------------------------------+
-| json_parse('{"k1":"v31","k2":300}') |
-+--------------------------------------+
-| {"k1":"v31","k2":300} |
-+--------------------------------------+
-```
-```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"}');
-```
-```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} |
-+-----------------------------------------------------------+
-```
+ ```sql
+ SELECT json_parse('{"k1":"v31","k2":300}');
+ ```
+ ```text
+ +-------------------------------------+
+ | json_parse('{"k1":"v31","k2":300}') |
+ +-------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +-------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_null('{"k1":"v31","k2":300}','{}');
+ ```
+ ```text
+ +---------------------------------------------------+
+ | json_parse_error_to_null('{"k1":"v31","k2":300}') |
+ +---------------------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +---------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('{"k1":"v31","k2":300}','{}');
+ ```
+ ```text
+ +---------------------------------------------------------+
+ | json_parse_error_to_value('{"k1":"v31","k2":300}','{}') |
+ +---------------------------------------------------------+
+ | {"k1":"v31","k2":300} |
+ +---------------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('{"k1":"v31","k2":300}', NULL);
+ ```
+ ```text
+ +----------------------------------------------------------+
+ | json_parse_error_to_value('{"k1":"v31","k2":300}', NULL) |
+ +----------------------------------------------------------+
+ | {"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
-```
-```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
-+-------------------------------------------+
-| jsonb_parse_error_to_null('invalid json') |
-+-------------------------------------------+
-| NULL |
-+-------------------------------------------+
-```
-```sql
-SELECT json_parse_error_to_value('invalid json', '{}');
-```
-```text
-+--------------------------------------------------+
-| json_parse_error_to_value('invalid json', '{}') |
-+--------------------------------------------------+
-| {} |
-+--------------------------------------------------+
-```
\ No newline at end of file
+ ```sql
+ SELECT json_parse('invalid json');
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]Parse
json document failed at row 0, error: [INTERNAL_ERROR]simdjson parse exception:
+ ```
+ ```sql
+ SELECT json_parse_error_to_null('invalid json');
+ ```
+ ```text
+ +------------------------------------------+
+ | json_parse_error_to_null('invalid json') |
+ +------------------------------------------+
+ | NULL |
+ +------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json');
+ ```
+ ```text
+ +-------------------------------------------+
+ | json_parse_error_to_value('invalid json') |
+ +-------------------------------------------+
+ | {} |
+ +-------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json', '{"key": "default
value"}');
+ ```
+ ```text
+ +-----------------------------------------------------------------------+
+ | json_parse_error_to_value('invalid json', '{"key": "default value"}') |
+ +-----------------------------------------------------------------------+
+ | {"key":"default value"} |
+ +-----------------------------------------------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value('invalid json', NULL);
+ ```
+ ```text
+ +-------------------------------------------------+
+ | json_parse_error_to_value('invalid json', NULL) |
+ +-------------------------------------------------+
+ | NULL |
+ +-------------------------------------------------+
+ ```
+3. NULL 参数
+ ```sql
+ SELECT json_parse(NULL);
+ ```
+ ```text
+ +------------------+
+ | json_parse(NULL) |
+ +------------------+
+ | NULL |
+ +------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_null(NULL);
+ ```
+ ```text
+ +--------------------------------+
+ | json_parse_error_to_null(NULL) |
+ +--------------------------------+
+ | NULL |
+ +--------------------------------+
+ ```
+ ```sql
+ SELECT json_parse_error_to_value(NULL, '{}');
+ ```
+ ```text
+ +---------------------------------------+
+ | json_parse_error_to_value(NULL, '{}') |
+ +---------------------------------------+
+ | NULL |
+ +---------------------------------------+
+ ```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
