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 e925430c6bb update JSON_ARRAY (#2582)
e925430c6bb is described below
commit e925430c6bb8c5752e5142a8e70e253409d67659
Author: Jerry Hu <[email protected]>
AuthorDate: Fri Jul 4 13:45:09 2025 +0800
update JSON_ARRAY (#2582)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../json-functions/json-array-ignore-null.md | 90 +++++++++++++
.../scalar-functions/json-functions/json-array.md | 142 +++++++++++---------
.../json-functions/json-array-ignore-null.md | 86 ++++++++++++
.../scalar-functions/json-functions/json-array.md | 146 ++++++++++++---------
4 files changed, 342 insertions(+), 122 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array-ignore-null.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array-ignore-null.md
new file mode 100644
index 00000000000..2c21e5c50af
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array-ignore-null.md
@@ -0,0 +1,90 @@
+---
+{
+ "title": "JSON_ARRAY_IGNORE_NULL",
+ "language": "en"
+}
+---
+
+
+# JSON_ARRAY_IGNORE_NULL
+## Description
+Generate a JSON array containing the specified elements. Returns an empty
array when no parameters are passed.
+
+## Syntax
+```sql
+JSON_ARRAY_IGNORE_NULL([<expression>, ...])
+```
+
+## Parameters
+### Variable parameters:
+- `<expression>`: Elements to be included in the JSON array. Can be single or
multiple values of different types, including NULL.
+
+## Return Value
+[`JSON`](../../../basic-element/sql-data-types/semi-structured/JSON.md):
Returns a JSON array composed of the parameter list.
+
+## Usage Notes
+- JSON_ARRAY_IGNORE_NULL implementation converts different types of parameters
to JSON values by implicitly calling the [`TO_JSON`](./to-json.md) function, so
parameters must be types supported by [`TO_JSON`](./to-json.md).
+- NULL will be ingored. If you DO want to retain null values in the array, you
can use the function [`JSON_ARRAY`](./json-array.md).
+- If the parameter type is not supported by [`TO_JSON`](./to-json.md), you
will get an error. You can first convert that parameter to String type, for
example:
+ ```sql
+ select JSON_ARRAY_IGNORE_NULL(CAST(NOW() as String));
+ ```
+ > The NOW() function returns a DateTime type, which needs to be converted
to String type using the CAST function
+- If the parameter is a JSON string and you want to add it to the array as a
JSON object, you should explicitly call the `JSON_PARSE` function to parse it
as a JSON object:
+ ```sql
+ select JSON_ARRAY_IGNORE_NULL(JSON_PARSE('{"key": "value"}'));
+ ```
+
+## Examples
+1. Regular parameters
+ ```sql
+ select json_array_ignore_null() as empty_array, json_array_ignore_null(1)
v1, json_array_ignore_null(1, 'abc') v2;
+ ```
+ ```
+ +-------------+------+-----------+
+ | empty_array | v1 | v2 |
+ +-------------+------+-----------+
+ | [] | [1] | [1,"abc"] |
+ +-------------+------+-----------+
+ ```
+2. NULL parameters
+ ```sql
+ select json_array_ignore_null(null) v1, json_array_ignore_null(1, null, 'I
am a string') v2;
+ ```
+ ```
+ +------+---------------------+
+ | v1 | v2 |
+ +------+---------------------+
+ | [] | [1,"I am a string"] |
+ +------+---------------------+
+ ```
+3. Unsupported parameter types
+ ```sql
+ select json_array_ignore_null('item1', map(123, 'abc'));
+ ```
+ ```
+ ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: to_json(MAP<TINYINT,VARCHAR(3)>)
+ ```
+4. Map type parameters can be explicitly converted to JSON
+
+ ```sql
+ select json_array_ignore_null(1, cast(map('key', 'value') as json));
+ ```
+ ```
+ +--------------------------------------------------------------+
+ | json_array_ignore_null(1, cast(map('key', 'value') as json)) |
+ +--------------------------------------------------------------+
+ | [1,{"key":"value"}] |
+ +--------------------------------------------------------------+
+ ```
+5. JSON strings can be parsed with `json_parse`
+ ```sql
+ select json_array_ignore_null(json_parse('{"key1": "value", "key2": [1, "I
am a string", 3]}'));
+ ```
+ ```
+
+------------------------------------------------------------------------------------------+
+ | json_array_ignore_null(json_parse('{"key1": "value", "key2": [1, "I am a
string", 3]}')) |
+
+------------------------------------------------------------------------------------------+
+ | [{"key1":"value","key2":[1,"I am a string",3]}]
|
+
+------------------------------------------------------------------------------------------+
+ ```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
index 4b1d0da7910..69da0a78dd3 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
@@ -5,71 +5,95 @@
}
---
+# JSON_ARRAY
## Description
-Generate a json array containing the specified values, return empty if no
values
-
+Generate a JSON array containing the specified elements. Returns an empty
array when no parameters are passed.
## Syntax
```sql
-JSON_ARRAY (<a>, ...)
+JSON_ARRAY([<expression>, ...])
```
## Parameters
-| Parameter | Description
|
-|------|---------------------------------------------------------------------------------------------------------------|
-| `<a>, ...` | Elements to be included in the JSON array. It can be a single
or multiple values of any type, including NULL. |
-
-
-## Return Values
-Returns a JSON array containing the specified values. If no values are
specified, an empty JSON array is returned.
-
+### Variable parameters:
+- `<expression>`: Elements to be included in the JSON array. Can be single or
multiple values of different types, including NULL.
+
+## Return Value
+[`JSON`](../../../basic-element/sql-data-types/semi-structured/JSON.md):
Returns a JSON array composed of the parameter list.
+
+## Usage Notes
+- JSON_ARRAY implementation converts different types of parameters to JSON
values by implicitly calling the [`TO_JSON`](./to-json.md) function, so
parameters must be types supported by [`TO_JSON`](./to-json.md)
+- NULL will be converted to JSON null. If you don't want to retain null values
in the array, you can use the function
[`JSON_ARRAY_IGNORE_NULL`](./json-array-ignore-null.md).
+- If the parameter type is not supported by [`TO_JSON`](./to-json.md), you
will get an error. You can first convert that parameter to String type, for
example:
+ ```sql
+ select JSON_ARRAY(CAST(NOW() as String));
+ ```
+ > The NOW() function returns a DateTime type, which needs to be converted
to String type using the CAST function
+- If the parameter is a JSON string and you want to add it to the array as a
JSON object, you should explicitly call the [`JSON_PARSE`](./json-parse.md)
function to parse it as a JSON object:
+ ```sql
+ select JSON_ARRAY(JSON_PARSE('{"key": "value"}'));
+ ```
## Examples
-
-```sql
-select json_array();
-```
-
-```text
-+--------------+
-| json_array() |
-+--------------+
-| [] |
-+--------------+
-```
-
-```sql
-select json_array(null);
-```
-
-```text
-+--------------------+
-| json_array('NULL') |
-+--------------------+
-| [NULL] |
-+--------------------+
-```
-```sql
-SELECT json_array(1, "abc", NULL, TRUE, CURTIME());
-```
-
-```text
-+-----------------------------------------------+
-| json_array(1, 'abc', 'NULL', TRUE, curtime()) |
-+-----------------------------------------------+
-| [1, "abc", NULL, TRUE, "10:41:15"] |
-+-----------------------------------------------+
-```
-
-```sql
-select json_array("a", null, "c");
-```
-
-```text
-+------------------------------+
-| json_array('a', 'NULL', 'c') |
-+------------------------------+
-| ["a", NULL, "c"] |
-+------------------------------+
-```
-
+1. Regular parameters
+ ```sql
+ select json_array() as empty_array, json_array(1) v1, json_array(1, 'abc')
v2;
+ ```
+ ```
+ +-------------+------+-----------+
+ | empty_array | v1 | v2 |
+ +-------------+------+-----------+
+ | [] | [1] | [1,"abc"] |
+ +-------------+------+-----------+
+ ```
+2. NULL parameters
+ ```sql
+ select json_array(null) v1, json_array(1, null, 'I am a string') v2;
+ ```
+ ```
+ +--------+--------------------------+
+ | v1 | v2 |
+ +--------+--------------------------+
+ | [null] | [1,null,"I am a string"] |
+ +--------+--------------------------+
+ ```
+3. Unsupported parameter types
+ ```sql
+ select json_array('item1', map(123, 'abc'));
+ ```
+ ```
+ ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: to_json(MAP<TINYINT,VARCHAR(3)>)
+ ```
+4. Map type parameters can be explicitly converted to JSON
+ ```sql
+ select json_array(1, cast(map('key', 'value') as json));
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_array(1, cast(map('key', 'value') as json)) |
+ +--------------------------------------------------+
+ | [1,{"key":"value"}] |
+ +--------------------------------------------------+
+ ```
+5. The JSON string will be added to the array in the form of a string
+ ```sql
+ select json_array('{"key1": "value", "key2": [1, "I am a string", 3]}');
+ ```
+ ```
+ +------------------------------------------------------------------+
+ | json_array('{"key1": "value", "key2": [1, "I am a string", 3]}') |
+ +------------------------------------------------------------------+
+ | ["{\"key1\": \"value\", \"key2\": [1, \"I am a string\", 3]}"] |
+ +------------------------------------------------------------------+
+ ```
+6. A JSON string can be parsed using `json_parse` and then passed to
`json_array`
+ ```sql
+ select json_array(json_parse('{"key1": "value", "key2": [1, "I am a
string", 3]}'));
+ ```
+ ```
+
+------------------------------------------------------------------------------+
+ | json_array(json_parse('{"key1": "value", "key2": [1, "I am a string",
3]}')) |
+
+------------------------------------------------------------------------------+
+ | [{"key1":"value","key2":[1,"I am a string",3]}]
|
+
+------------------------------------------------------------------------------+
+ ```
\ 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-array-ignore-null.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-array-ignore-null.md
new file mode 100644
index 00000000000..45c5532d2a9
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-array-ignore-null.md
@@ -0,0 +1,86 @@
+---
+{
+ "title": "JSON_ARRAY_IGNORE_NULL",
+ "language": "zh-CN"
+}
+---
+
+# JSON_ARRAY_IGNORE_NULL
+## 功能
+生成一个包含指定元素的 json 数组，未传入参数时返回空数组，它与 [`JSON_ARRAY`](./json-array.md)
只有一个区别：会忽略值为 NULL 的参数。
+## 语法
+```sql
+JSON_ARRAY_IGNORE_NULL([<expression>, ...])
+```
+## 参数
+### 可变参数：
+- `<expression>`: 要包含在 JSON 数组中的元素。可以是单个或者多种类型的值，包括NULL。
+## 返回值
+[`JSON`](../../../basic-element/sql-data-types/semi-structured/JSON.md)：
返回由参数列表组成的 JSON 数组。
+
+## 使用说明
+- JSON_ARRAY_IGNORE_NULL 的实现是通过将不同类型的参数通过隐式调用 [`TO_JSON`](./to-json.md)
函数将其转换为 Json 值，所以参数必须是 [`TO_JSON`](./to-json.md) 支持的类型
+- NULL 会丢弃, 如果希望在数组中保留 NULL 值，可以使用函数 [`JSON_ARRAY`](./json-array.md).
+- 如果参数类型不被 [`TO_JSON`](./to-json.md) 支持，那么会得到错误，可以先将该参数转换为 String 类型，比如:
+ ```sql
+ select JSON_ARRAY_IGNORE_NULL(CAST(NOW() as String));
+ ```
+ > NOW() 函数得到的是 DateTime 类型，需要通过 CAST 函数转换为 String 类型
+- 如果参数是 Json 字符串并且希望将其作为 Json 对象加入到数组中，应该显式调用 [`JSON_PARSE`](./json-parse.md)
函数将其解析为 Json 对象：
+ ```sql
+ select JSON_ARRAY_IGNORE_NULL(JSON_PARSE('{"key": "value"}'));
+ ```
+
+## 示例
+1. 常规参数
+ ```sql
+ select json_array_ignore_null() as empty_array, json_array_ignore_null(1)
v1, json_array_ignore_null(1, 'abc') v2;
+ ```
+ ```
+ +-------------+------+-----------+
+ | empty_array | v1 | v2 |
+ +-------------+------+-----------+
+ | [] | [1] | [1,"abc"] |
+ +-------------+------+-----------+
+ ```
+2. NULL 参数
+ ```sql
+ select json_array_ignore_null(null) v1, json_array_ignore_null(1, null, 'I
am a string') v2;
+ ```
+ ```
+ +------+---------------------+
+ | v1 | v2 |
+ +------+---------------------+
+ | [] | [1,"I am a string"] |
+ +------+---------------------+
+ ```
+3. 不支持的参数类型
+ ```sql
+ select json_array_ignore_null('item1', map(123, 'abc'));
+ ```
+ ```
+ ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: to_json(MAP<TINYINT,VARCHAR(3)>)
+ ```
+4. Map 类型参数可以先显式转换为 JSON
+
+ ```sql
+ select json_array_ignore_null(1, cast(map('key', 'value') as json));
+ ```
+ ```
+ +--------------------------------------------------------------+
+ | json_array_ignore_null(1, cast(map('key', 'value') as json)) |
+ +--------------------------------------------------------------+
+ | [1,{"key":"value"}] |
+ +--------------------------------------------------------------+
+ ```
+5. Json 字符串可以用 json_parse 解析
+ ```sql
+ select json_array_ignore_null(json_parse('{"key1": "value", "key2": [1, "I
am a string", 3]}'));
+ ```
+ ```
+
+------------------------------------------------------------------------------------------+
+ | json_array_ignore_null(json_parse('{"key1": "value", "key2": [1, "I am a
string", 3]}')) |
+
+------------------------------------------------------------------------------------------+
+ | [{"key1":"value","key2":[1,"I am a string",3]}]
|
+
+------------------------------------------------------------------------------------------+
+ ```
\ 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-array.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
index cb743dfb94e..1a1d7931da5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-array.md
@@ -5,73 +5,93 @@
}
---
-## 描述
-
-生成一个包含制定元素的 json 数组，未指定时返回空数组
-
+# JSON_ARRAY
+## 功能
+生成一个包含指定元素的 json 数组，未传入参数时返回空数组。
## 语法
-
```sql
-JSON_ARRAY(<a>, ...)
+JSON_ARRAY([<expression>, ...])
```
-
## 参数
-
-| 参数 | 描述 |
-|------|------------------------------------------------------------|
-| `<a>, ...` | 要包含在 JSON 数组中的元素。可以是单个或者多个任意类型的值，包括`NULL`。如果没有指定元素，则返回一个空数组。 |
-
+### 可变参数：
+- `<expression>`: 要包含在 JSON 数组中的元素。可以是单个或者多种类型的值，包括NULL。
## 返回值
-
-返回一个包含指定元素的 JSON 数组。特殊情况：
-* 如果指定的元素为`NULL`，则返回`NULL`。
+[`JSON`](../../../basic-element/sql-data-types/semi-structured/JSON.md)：
返回由参数列表组成的 JSON 数组。
+
+## 使用说明
+- JSON_ARRAY 的实现是通过将不同类型的参数通过隐式调用 [`TO_JSON`](./to-json.md) 函数将其转换为 Json
值，所以参数必须是 [`TO_JSON`](./to-json.md) 支持的类型
+- NULL 会被转换为 Json 的 null, 如果不希望在数组中保留 null 值，可以使用函数
[`JSON_ARRAY_IGNORE_NULL`](./json-array-ignore-null.md).
+- 如果参数类型不被 [`TO_JSON`](./to-json.md) 支持，那么会得到错误，可以先将该参数转换为 String 类型，比如:
+ ```sql
+ select JSON_ARRAY(CAST(NOW() as String));
+ ```
+ > NOW() 函数得到的是 DateTime 类型，需要通过 CAST 函数转换为 String 类型
+- 如果参数是 Json 字符串并且希望将其作为 Json 对象加入到数组中，应该显式调用 [`JSON_PARSE`](./json-parse.md)
函数将其解析为 Json 对象：
+ ```sql
+ select JSON_ARRAY(JSON_PARSE('{"key": "value"}'));
+ ```
## 示例
-
-```sql
-select json_array();
-```
-
-```text
-+--------------+
-| json_array() |
-+--------------+
-| [] |
-+--------------+
-```
-
-```sql
-select json_array(null);
-```
-
-```text
-+--------------------+
-| json_array('NULL') |
-+--------------------+
-| [NULL] |
-+--------------------+
-```
-
-```sql
-SELECT json_array(1, "abc", NULL, TRUE, CURTIME());
-```
-
-```text
-+-----------------------------------------------+
-| json_array(1, 'abc', 'NULL', TRUE, curtime()) |
-+-----------------------------------------------+
-| [1, "abc", NULL, TRUE, "10:41:15"] |
-+-----------------------------------------------+
-```
-
-```sql
-select json_array("a", null, "c");
-```
-
-```text
-+------------------------------+
-| json_array('a', 'NULL', 'c') |
-+------------------------------+
-| ["a", NULL, "c"] |
-+------------------------------+
-```
+1. 常规参数
+ ```sql
+ select json_array() as empty_array, json_array(1) v1, json_array(1, 'abc')
v2;
+ ```
+ ```
+ +-------------+------+-----------+
+ | empty_array | v1 | v2 |
+ +-------------+------+-----------+
+ | [] | [1] | [1,"abc"] |
+ +-------------+------+-----------+
+ ```
+2. NULL 参数
+ ```sql
+ select json_array(null) v1, json_array(1, null, 'I am a string') v2;
+ ```
+ ```
+ +--------+--------------------------+
+ | v1 | v2 |
+ +--------+--------------------------+
+ | [null] | [1,null,"I am a string"] |
+ +--------+--------------------------+
+ ```
+3. 不支持的参数类型
+ ```sql
+ select json_array('item1', map(123, 'abc'));
+ ```
+ ```
+ ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: to_json(MAP<TINYINT,VARCHAR(3)>)
+ ```
+4. Map 类型参数可以先显式转换为 JSON
+
+ ```sql
+ select json_array(1, cast(map('key', 'value') as json));
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_array(1, cast(map('key', 'value') as json)) |
+ +--------------------------------------------------+
+ | [1,{"key":"value"}] |
+ +--------------------------------------------------+
+ ```
+5. Json 字符串会以字符串的形式被添加到数组中
+ ```sql
+ select json_array('{"key1": "value", "key2": [1, "I am a string", 3]}');
+ ```
+ ```
+ +------------------------------------------------------------------+
+ | json_array('{"key1": "value", "key2": [1, "I am a string", 3]}') |
+ +------------------------------------------------------------------+
+ | ["{\"key1\": \"value\", \"key2\": [1, \"I am a string\", 3]}"] |
+ +------------------------------------------------------------------+
+ ```
+6. Json 字符串可以用 `json_parse` 解析之后传入到 `json_array`
+ ```sql
+ select json_array(json_parse('{"key1": "value", "key2": [1, "I am a
string", 3]}'));
+ ```
+ ```
+
+------------------------------------------------------------------------------+
+ | json_array(json_parse('{"key1": "value", "key2": [1, "I am a string",
3]}')) |
+
+------------------------------------------------------------------------------+
+ | [{"key1":"value","key2":[1,"I am a string",3]}]
|
+
+------------------------------------------------------------------------------+
+ ```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
