This is an automated email from the ASF dual-hosted git repository.
mrhhsg 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 ab84aceedbc Update json modify (#2621)
ab84aceedbc is described below
commit ab84aceedbcec7e1cadf5760fde96737ab65f5e2
Author: Jerry Hu <[email protected]>
AuthorDate: Tue Jul 15 15:47:36 2025 +0800
Update json modify (#2621)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../scalar-functions/json-functions/json-insert.md | 170 +++++++++++++--------
.../json-functions/json-replace.md | 130 +++++++++-------
.../scalar-functions/json-functions/json-set.md | 114 +++++++-------
.../scalar-functions/json-functions/json-insert.md | 162 +++++++++++++-------
.../json-functions/json-replace.md | 128 +++++++++-------
.../scalar-functions/json-functions/json-set.md | 109 +++++++------
6 files changed, 480 insertions(+), 333 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
index 6a1aef8b434..63a0536f0f1 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
@@ -6,75 +6,119 @@
---
## Description
-The JSON_INSERT function is used to insert data into JSON and return the
result.
-
+The `JSON_INSERT` function is used to insert data into JSON and return the
result.
## Syntax
```sql
-JSON_INSERT (<json_str>, <path>, <val>[, <path>, <val>, ...])
+JSON_INSERT (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
## Parameters
-| Parameter | Description
|
-|-------------|--------------------------------------------------------------------------------------------------------------------------------|
-| `<json_str>` | The JSON object to be inserted. It can be a JSON object with
elements of any type, including NULL. If no elements are specified, an empty
array is returned. If json_str is not a valid JSON or any path parameter is not
a valid path expression or contains a * wildcard, an error is returned. |
-| `<path>` | The JSON path to be inserted. If it is NULL, then return NULL.
|
-| `<val>` | The value to be inserted into the JSON. If it is NULL, then
a NULL value will be inserted at the corresponding position.
|
-
-`json_insert` function inserts data in a JSON and returns the result.Returns
NULL if `json_str` or `path` is NULL. Otherwise, an error occurs if the
`json_str` argument is not a valid JSON or any path argument is not a valid
path expression or contains a * wildcard.
-
-The path-value pairs are evaluated left to right.
-
-A path-value pair for a nonexisting path in the json adds the value to the
json if the path identifies one of these types of values:
-
-* A member not present in an existing object. The member is added to the
object and associated with the new value.
+- `<json_object>`: JSON type expression, the target to be modified.
+- `<path>`: String type expression, specifies the path where the value is to
be inserted
+- `<value>`: JSON type or other types supported by [`TO_JSON`](./to-json.md),
the value to be inserted.
-* A position past the end of an existing array. The array is extended with the
new value. If the existing value is not an array, it is autowrapped as an
array, then extended with the new value.
+## Return Value
+- Nullable(JSON) Returns the modified JSON object
-Otherwise, a path-value pair for a nonexisting path in the json is ignored and
has no effect.
+## Usage Notes
+1. Note that path-value pairs are evaluated from left to right.
+2. If the value pointed to by `<path>` already exists in the JSON object, it
will have no effect.
+3. `<path>` cannot contain wildcards, if it contains wildcards an error will
be reported.
+4. If `<path>` contains multiple levels of paths, all paths except the last
level must exist in the JSON object.
+5. If `<path>` points to an array member element, but the object is not
actually an array, then the object will be converted to the first member of the
array, and then processed as a normal array.
+6. When `<json_object>` or `<path>` is NULL, NULL will be returned. If
`<value>` is NULL, a JSON null value will be inserted.
-## Return Values
-Returns a JSON value.
-
-### Examples
-
-```sql
-select json_insert(null, null, null);
-```
-```text
-+---------------------------------+
-| json_insert(NULL, NULL, 'NULL') |
-+---------------------------------+
-| NULL |
-+---------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.k", 2);
-```
-```text
-+---------------------------------------+
-| json_insert('{\"k\": 1}', '$.k', '2') |
-+---------------------------------------+
-| {"k":1} |
-+---------------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.j", 2);
-```
-```text
-+---------------------------------------+
-| json_insert('{\"k\": 1}', '$.j', '2') |
-+---------------------------------------+
-| {"k":1,"j":2} |
-+---------------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.j", null);
-```
-```text
-+-----------------------------------------------+
-| json_insert('{"k": 1}', '$.j', 'NULL', '660') |
-+-----------------------------------------------+
-| {"k":1,"j":null} |
-+-----------------------------------------------+
-```
+## Examples
+1. Path-value pairs are evaluated from left to right
+ ```sql
+ select json_insert('{}', '$.k', json_parse('{}'), '$.k.k2', 123);
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | json_insert('{}', '$.k', json_parse('{}'), '$.k.k2', 123) |
+ +-----------------------------------------------------------+
+ | {"k":{"k2":123}} |
+ +-----------------------------------------------------------+
+ ```
+2. Value pointed to by `<path>` already exists in the JSON object
+ ```sql
+ select json_insert('{"k": 1}', "$.k", 2);
+ ```
+ ```text
+ +-----------------------------------+
+ | json_insert('{"k": 1}', "$.k", 2) |
+ +-----------------------------------+
+ | {"k":1} |
+ +-----------------------------------+
+ ```
+3. `<path>` cannot contain wildcards
+ ```sql
+ select json_insert('{"k": 1}', "$.*", 2);
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT] In
this situation, path expressions may not contain the * and ** tokens or an
array range, argument index: 1, row index: 0
+ ```
+4. Cannot create multi-level paths
+ ```sql
+ select json_insert('{}', '$.k1.k2.k3', 123);
+ ```
+ ```text
+ +--------------------------------------+
+ | json_insert('{}', '$.k1.k2.k3', 123) |
+ +--------------------------------------+
+ | {} |
+ +--------------------------------------+
+ ```
+5. Automatic conversion to array
+ ```sql
+ select json_insert('{"k": "v"}', '$[1]', 123);
+ ```
+ ```text
+ +----------------------------------------+
+ | json_insert('{"k": "v"}', '$[1]', 123) |
+ +----------------------------------------+
+ | [{"k": "v"}, 123] |
+ +----------------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', '$.k[1]', 123);
+ ```
+ ```text
+ +------------------------------------------+
+ | json_insert('{"k": "v"}', '$.k[1]', 123) |
+ +------------------------------------------+
+ | {"k": ["v", 123]} |
+ +------------------------------------------+
+ ```
+6. NULL parameters
+ ```sql
+ select json_insert(NULL, '$[1]', 123);
+ ```
+ ```text
+ +--------------------------------+
+ | json_insert(NULL, '$[1]', 123) |
+ +--------------------------------+
+ | NULL |
+ +--------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +--------------------------------------+
+ | json_insert('{"k": "v"}', NULL, 123) |
+ +--------------------------------------+
+ | NULL |
+ +--------------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', '$.k[1]', NULL);
+ ```
+ ```text
+ +-------------------------------------------+
+ | json_insert('{"k": "v"}', '$.k[1]', NULL) |
+ +-------------------------------------------+
+ | {"k": ["v", null]} |
+ +-------------------------------------------+
+ ```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
index 9eeb3364089..fb5d4c3c4a7 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
@@ -6,69 +6,85 @@
---
## Description
-The JSON_REPLACE function is used to update data in a JSON and return the
result.
+The `JSON_REPLACE` function is used to replace data in JSON and return the
result.
## Syntax
```sql
-JSON_REPLACE (<json_str>, <path>, <val>[, <jsonPath>, <val>, ...])
+JSON_REPLACE (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
## Parameters
-| Parameter | Description
|
-|--------------|---------------------------------------------------------------------------------------------|
-| `<json_str>` | The JSON data to be replaced. It can be a JSON object with
elements of any type, including NULL. If no elements are specified, an empty
array is returned. If json_str is not a valid JSON, an error will be returned. |
-| `<path>` | The JSON path to be replaced.
|
-| `<val>` | The value to replace the value corresponding to the JSON_PATH
Key. If it is NULL, then a NULL value will be inserted at the corresponding
position. |
+- `<json_object>`: JSON type expression, the target to be modified.
+- `<path>`: String type expression, specifies the path where the value is to
be replaced
+- `<value>`: JSON type or other types supported by [`TO_JSON`](./to-json.md),
the value to be replaced.
-## Return Values
+## Return Value
+- Nullable(JSON) Returns the modified JSON object
-`json_replace` function updates data in a JSON and returns the result.Returns
NULL if `json_str` or `path` is NULL. Otherwise, an error occurs if the
`json_str` argument is not a valid JSON or any path argument is not a valid
path expression or contains a * wildcard.
+## Usage Notes
+1. Note that path-value pairs are evaluated from left to right.
+2. If the value pointed to by `<path>` does not exist in the JSON object, it
will have no effect.
+3. `<path>` cannot contain wildcards, if it contains wildcards an error will
be reported.
+4. When `<json_object>` or `<path>` is NULL, NULL will be returned. If
`<value>` is NULL, a JSON null value will be inserted.
-The path-value pairs are evaluated left to right.
-
-A path-value pair for an existing path in the json overwrites the existing
json value with the new value.
-
-Otherwise, a path-value pair for a nonexisting path in the json is ignored and
has no effect.
-
-### Examples
-
-```sql
-select json_replace(null, null, null);
-```
-```text
-+----------------------------------+
-| json_replace(NULL, NULL, 'NULL') |
-+----------------------------------+
-| NULL |
-+----------------------------------+
-```
-```sql
-select json_replace('{"k": 1}', "$.k", 2);
-```
-```text
-+----------------------------------------+
-| json_replace('{\"k\": 1}', '$.k', '2') |
-+----------------------------------------+
-| {"k":2} |
-+----------------------------------------+
-```
-```sql
-select json_replace('{"k": 1}', "$.j", 2);
-```
-```text
-+----------------------------------------+
-| json_replace('{\"k\": 1}', '$.j', '2') |
-+----------------------------------------+
-| {"k":1} |
-+----------------------------------------+
-```
-```sql
-select json_replace(null, null, 's');
-```
-```text
-+--------------------------------------+
-| json_replace(NULL, NULL, 's', '006') |
-+--------------------------------------+
-| NULL |
-+--------------------------------------+
-```
+## Examples
+1. Path-value pairs are evaluated from left to right
+ ```sql
+ select json_replace('{"k": {"k2": "v2"}}', '$.k', json_parse('{"k2": 321,
"k3": 456}'), '$.k.k2', 123);
+ ```
+ ```text
+
+-------------------------------------------------------------------------------------------------+
+ | json_replace('{"k": {"k2": "v2"}}', '$.k', json_parse('{"k2": 321, "k3":
456}'), '$.k.k2', 123) |
+
+-------------------------------------------------------------------------------------------------+
+ | {"k":{"k2":123,"k3":456}}
|
+
+-------------------------------------------------------------------------------------------------+
+ ```
+2. Value pointed to by `<path>` does not exist in the JSON object
+ ```sql
+ select json_replace('{"k": 1}', "$.k2", 2);
+ ```
+ ```text
+ +-------------------------------------+
+ | json_replace('{"k": 1}', "$.k2", 2) |
+ +-------------------------------------+
+ | {"k":1} |
+ +-------------------------------------+
+ ```
+3. `<path>` cannot contain wildcards
+ ```sql
+ select json_replace('{"k": 1}', "$.*", 2);
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT] In
this situation, path expressions may not contain the * and ** tokens or an
array range, argument index: 1, row index: 0
+ ```
+4. NULL parameters
+ ```sql
+ select json_replace(NULL, '$[1]', 123);
+ ```
+ ```text
+ +---------------------------------+
+ | json_replace(NULL, '$[1]', 123) |
+ +---------------------------------+
+ | NULL |
+ +---------------------------------+
+ ```
+ ```sql
+ select json_replace('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +---------------------------------------+
+ | json_replace('{"k": "v"}', NULL, 123) |
+ +---------------------------------------+
+ | NULL |
+ +---------------------------------------+
+ ```
+ ```sql
+ select json_replace('{"k": "v"}', '$.k', NULL);
+ ```
+ ```text
+ +-----------------------------------------+
+ | json_replace('{"k": "v"}', '$.k', NULL) |
+ +-----------------------------------------+
+ | {"k":null} |
+ +-----------------------------------------+
+ ```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
index 66de213698e..9be8f26be72 100644
--- a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
+++ b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
@@ -6,65 +6,75 @@
---
## Description
-The json_set function inserts or updates data in a JSON and returns the result.
+The `JSON_SET` function is used to insert or replace data in JSON and return
the result.
## Syntax
```sql
-JSON_SET (<json_str>, <path>, <val> [, <path>, <val>, ...])
+JSON_SET (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
## Parameters
+- `<json_object>`: JSON type expression, the target to be modified.
+- `<path>`: String type expression, specifies the path where the value is to
be inserted
+- `<value>`: JSON type or other types supported by [`TO_JSON`](./to-json.md),
the value to be inserted.
-| Parameter | Description
|
-|-------|-------------------------------------------------------------------------------------------------------------------------|
-| `<jsonStr>` | The JSON object to be inserted. It can be a JSON object with
elements of any type, including NULL. If no elements are specified, an empty
array is returned. If json_str is not a valid JSON or any path parameter is not
a valid path expression or contains a * wildcard, an error is returned. |
-| `<jsonPath>` | The JSON path to be inserted. If it is NULL, then return
NULL.
|
-| `<val>` | The value to be inserted into the JSON. If it is NULL, then a NULL
value will be inserted at the corresponding position.
|
+## Return Value
+- Nullable(JSON) Returns the modified JSON object
-## Return Values
-Returns a JSON value.
-
-`json_set` function inserts or updates data in a JSON and returns the
result.Returns NULL if `json_str` or `path` is NULL. Otherwise, an error occurs
if the `json_str` argument is not a valid JSON or any path argument is not a
valid path expression or contains a * wildcard.
-
-The path-value pairs are evaluated left to right.
-
-A path-value pair for an existing path in the json overwrites the existing
json value with the new value. A path-value pair for a nonexisting path in the
json adds the value to the json if the path identifies one of these types of
values:
-
-* A member not present in an existing object. The member is added to the
object and associated with the new value.
-
-* A position past the end of an existing array. The array is extended with the
new value. If the existing value is not an array, it is autowrapped as an
array, then extended with the new value.
-
-Otherwise, a path-value pair for a nonexisting path in the json is ignored and
has no effect.
+## Usage Notes
+1. When the object pointed to by `<path>` exists, its behavior is consistent
with [`JSON_REPLACE`](./json-replace.md), otherwise its behavior is consistent
with [`JSON_INSERT`](./json-insert.md)
## Examples
-
-```sql
-select json_set(null, null, null);
-```
-```text
-+------------------------------+
-| json_set(NULL, NULL, 'NULL') |
-+------------------------------+
-| NULL |
-+------------------------------+
-```
-```sql
-select json_set('{"k": 1}', "$.k", 2);
-```
-```text
-+------------------------------------+
-| json_set('{\"k\": 1}', '$.k', '2') |
-+------------------------------------+
-| {"k":2} |
-+------------------------------------+
-```
-```sql
-select json_set('{"k": 1}', "$.j", 2);
-```
-```text
-+------------------------------------+
-| json_set('{\"k\": 1}', '$.j', '2') |
-+------------------------------------+
-| {"k":1,"j":2} |
-+------------------------------------+
-```
+1. Path does not exist
+ ```sql
+ select json_set('{}', '$.k', json_parse('{}'), '$.k.k2', 123);
+ ```
+ ```text
+ +--------------------------------------------------------+
+ | json_set('{}', '$.k', json_parse('{}'), '$.k.k2', 123) |
+ +--------------------------------------------------------+
+ | {"k":{"k2":123}} |
+ +--------------------------------------------------------+
+ ```
+2. Value pointed to by `<path>` already exists in the JSON object
+ ```sql
+ select json_set('{"k": 1}', "$.k", 2);
+ ```
+ ```text
+ +--------------------------------+
+ | json_set('{"k": 1}', "$.k", 2) |
+ +--------------------------------+
+ | {"k":2} |
+ +--------------------------------+
+ ```
+3. NULL parameters
+ ```sql
+ select json_set(NULL, '$[1]', 123);
+ ```
+ ```text
+ +-----------------------------+
+ | json_set(NULL, '$[1]', 123) |
+ +-----------------------------+
+ | NULL |
+ +-----------------------------+
+ ```
+ ```sql
+ select json_set('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +-----------------------------------+
+ | json_set('{"k": "v"}', NULL, 123) |
+ +-----------------------------------+
+ | NULL |
+ +-----------------------------------+
+ ```
+ ```sql
+ select json_set('{"k": "v"}', '$.k[1]', NULL);
+ ```
+ ```text
+ +----------------------------------------+
+ | json_set('{"k": "v"}', '$.k[1]', NULL) |
+ +----------------------------------------+
+ | {"k":["v",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-insert.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
index 134c85e3a2b..b97c152fde8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-insert.md
@@ -10,67 +10,115 @@
## 语法
```sql
-JSON_INSERT (<json_str>, <path>, <val>[, <path>, <val>, ...])
+JSON_INSERT (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
## 参数
-| 参数 | 描述
|
-|-------------|--------------------------------------------------------------------------------------------------------------------------------|
-| `<json_str>` | 要插入的 JSON 对象。可以是任意类型元素的 JSON 对象，包括`NULL`，如果没有指定元素，则返回一个空数组。如果
`json_str` 不是有效的 JSON 或任何 `path` 参数不是有效的路径表达式或包含了 * 通配符，则会返回错误 |
-| `<path>` | 要插入的 JSON 路径。如果是 `NULL` ，则返回 NULL
|
-| `<val>` | 要插入 JSON 的值。如果是 `NULL` ，则会在对应的位置插入 `NULL` 的 value 值。
|
-
-
-需要注意的是，路径值对按从左到右的顺序进行评估。
-
-如果 JSON 中不存在该路径，则路径值对会添加该值到 JSON 中，如果路径标识某个类型的值，则：
-
-* 对于现有对象中不存在的成员，会将新成员添加到该对象中并与新值相关联。
-* 对于现有数组结束后的位置，该数组将扩展为包含新值。如果现有值不是数组，则自动转换为数组，然后再扩展为包含新值的数组。
-
-否则，对于 JSON 中不存在的某个路径的路径值对将被忽略且不会产生任何影响。
+- `<json_object>` JSON 类型表达式，被修改的目标。
+- `<path>` String 类型表达式，指定插入值的路径
+- `<value>` JSON 类型或其他 [`TO_JSON`](./to-json.md) 支持的类型，要插入的值。
## 返回值
-返回一个 JSON 值。
+- Nullable(JSON) 返回被修改后的 JSON 对象
+
+## 使用说明
+1. 需要注意的是，路径值对按从左到右的顺序进行评估。
+2. 如果 `<path>` 指向的值在 JSON 对象中已经存在，不会产生任何影响。
+3. `<path>` 中不能包含通配符，如果包含通配符会报错。
+4. 如果 `<path>` 中包含多层路径，除了最后一层路径其他路径必须存在于 JSON 对象中。
+5. 如果 `<path>` 指向的是某个数组成员元素，但实际上这个对象并不是数组，那么会将该对象转换为数组的第一个成员，然后按照正常的数组处理。
+6. `<json_object>` 或者 `<path>` 为 NULL 时，会得到 NULL，如果 `<value>` 为 NULL 会插入一个
JSON 的 null 值。
## 示例
-```sql
-select json_insert(null, null, null);
-```
-```text
-+---------------------------------+
-| json_insert(NULL, NULL, 'NULL') |
-+---------------------------------+
-| NULL |
-+---------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.k", 2);
-```
-```text
-+---------------------------------------+
-| json_insert('{\"k\": 1}', '$.k', '2') |
-+---------------------------------------+
-| {"k":1} |
-+---------------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.j", 2);
-```
-```text
-+---------------------------------------+
-| json_insert('{\"k\": 1}', '$.j', '2') |
-+---------------------------------------+
-| {"k":1,"j":2} |
-+---------------------------------------+
-```
-```sql
-select json_insert('{"k": 1}', "$.j", null);
-```
-```text
-+-----------------------------------------------+
-| json_insert('{"k": 1}', '$.j', 'NULL', '660') |
-+-----------------------------------------------+
-| {"k":1,"j":null} |
-+-----------------------------------------------+
-```
\ No newline at end of file
+1. 路径值对按从左到右的顺序进行评估
+ ```sql
+ select json_insert('{}', '$.k', json_parse('{}'), '$.k.k2', 123);
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | json_insert('{}', '$.k', json_parse('{}'), '$.k.k2', 123) |
+ +-----------------------------------------------------------+
+ | {"k":{"k2":123}} |
+ +-----------------------------------------------------------+
+ ```
+2. `<path>` 指向的值在 JSON 对象中已经存在
+ ```sql
+ select json_insert('{"k": 1}', "$.k", 2);
+ ```
+ ```text
+ +-----------------------------------+
+ | json_insert('{"k": 1}', "$.k", 2) |
+ +-----------------------------------+
+ | {"k":1} |
+ +-----------------------------------+
+ ```
+3. `<path>` 不能包含通配符
+ ```sql
+ select json_insert('{"k": 1}', "$.*", 2);
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT] In
this situation, path expressions may not contain the * and ** tokens or an
array range, argument index: 1, row index: 0
+ ```
+4. 无法创建多层路径
+ ```sql
+
+ ```
+ ```text
+ +--------------------------------------+
+ | json_insert('{}', '$.k1.k2.k3', 123) |
+ +--------------------------------------+
+ | {} |
+ +--------------------------------------+
+ ```
+5. 自动转换为数组的情况
+ ```sql
+ select json_insert('{"k": "v"}', '$[1]', 123);
+ ```
+ ```text
+ +----------------------------------------+
+ | json_insert('{"k": "v"}', '$[1]', 123) |
+ +----------------------------------------+
+ | [{"k": "v"}, 123] |
+ +----------------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', '$.k[1]', 123);
+ ```
+ ```text
+ +------------------------------------------+
+ | json_insert('{"k": "v"}', '$.k[1]', 123) |
+ +------------------------------------------+
+ | {"k": ["v", 123]} |
+ +------------------------------------------+
+ ```
+6. NULL 参数
+ ```sql
+ select json_insert(NULL, '$[1]', 123);
+ ```
+ ```text
+ +--------------------------------+
+ | json_insert(NULL, '$[1]', 123) |
+ +--------------------------------+
+ | NULL |
+ +--------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +--------------------------------------+
+ | json_insert('{"k": "v"}', NULL, 123) |
+ +--------------------------------------+
+ | NULL |
+ +--------------------------------------+
+ ```
+ ```sql
+ select json_insert('{"k": "v"}', '$.k[1]', NULL);
+ ```
+ ```text
+ +-------------------------------------------+
+ | json_insert('{"k": "v"}', '$.k[1]', NULL) |
+ +-------------------------------------------+
+ | {"k": ["v", 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-replace.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
index f2208d54c9c..7fa88eff211 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-replace.md
@@ -6,69 +6,85 @@
---
## 描述
-`JSON_REPLACE` 函数用于在 JSON 中更新数据并返回结果。
+`JSON_REPLACE` 函数用于在 JSON 中插入数据并返回结果。
## 语法
```sql
-JSON_REPLACE (<json_str>, <path>, <val>[, <jsonPath>, <val>, ...])
+JSON_REPLACE (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
-## 参数
-| 参数 | 描述
|
-|--------------|---------------------------------------------------------------------------------------------|
-| `<json_str>` | 要替换的 JSON 数据。可以是任意类型元素的 JSON
对象，包括`NULL`，如果没有指定元素，则返回一个空数组。如果 `json_str` 不是有效的 JSON，则会返回错误 |
-| `<path>` | 要替换的 JSON 路径。
|
-| `<val>` | 要替换 JSON_PATH Key 对应 value 的值。如果是 `NULL` ，则会在对应的位置插入 `NULL` 的
value 值。 |
+## 参数
+- `<json_object>` JSON 类型表达式，被修改的目标。
+- `<path>` String 类型表达式，指定替换值的路径
+- `<value>` JSON 类型或其他 [`TO_JSON`](./to-json.md) 支持的类型，要替换的值。
## 返回值
+- Nullable(JSON) 返回被修改后的 JSON 对象
-如果 `json_str` 和 `path` 都为 NULL，则返回 NULL。
-
-否则，如果 `json_str` 不是有效的 JSON 或任何 `path` 参数不是有效的路径表达式或包含了 * 通配符，则会返回错误。
-
-路径值对按从左到右的顺序进行评估。
-
-如果 JSON 中已存在某个路径，则路径值对会将现有 JSON 值覆盖为新值。否则，对于 JSON 中不存在的某个路径的路径值对将被忽略且不会产生任何影响。
+## 使用说明
+1. 需要注意的是，路径值对按从左到右的顺序进行评估。
+2. 如果 `<path>` 指向的值在 JSON 对象中不存在，不会产生任何影响。
+3. `<path>` 中不能包含通配符，如果包含通配符会报错。
+4. `<json_object>` 或者 `<path>` 为 NULL 时，会得到 NULL，如果 `<value>` 为 NULL 会插入一个
JSON 的 null 值。
## 示例
-
-```sql
-select json_replace(null, null, null);
-```
-```text
-+----------------------------------+
-| json_replace(NULL, NULL, 'NULL') |
-+----------------------------------+
-| NULL |
-+----------------------------------+
-```
-```sql
-select json_replace('{"k": 1}', "$.k", 2);
-```
-```text
-+----------------------------------------+
-| json_replace('{\"k\": 1}', '$.k', '2') |
-+----------------------------------------+
-| {"k":2} |
-+----------------------------------------+
-```
-```sql
-select json_replace('{"k": 1}', "$.j", 2);
-```
-```text
-+----------------------------------------+
-| json_replace('{\"k\": 1}', '$.j', '2') |
-+----------------------------------------+
-| {"k":1} |
-+----------------------------------------+
-```
-```sql
-select json_replace(null, null, 's');
-```
-```text
-+--------------------------------------+
-| json_replace(NULL, NULL, 's', '006') |
-+--------------------------------------+
-| NULL |
-+--------------------------------------+
-```
+1. 路径值对按从左到右的顺序进行评估
+ ```sql
+ select json_replace('{"k": {"k2": "v2"}}', '$.k', json_parse('{"k2": 321,
"k3": 456}'), '$.k.k2', 123);
+ ```
+ ```text
+
+-------------------------------------------------------------------------------------------------+
+ | json_replace('{"k": {"k2": "v2"}}', '$.k', json_parse('{"k2": 321, "k3":
456}'), '$.k.k2', 123) |
+
+-------------------------------------------------------------------------------------------------+
+ | {"k":{"k2":123,"k3":456}}
|
+
+-------------------------------------------------------------------------------------------------+
+ ```
+2. `<path>` 指向的值在 JSON 对象中不存在
+ ```sql
+ select json_replace('{"k": 1}', "$.k2", 2);
+ ```
+ ```text
+ +-------------------------------------+
+ | json_replace('{"k": 1}', "$.k2", 2) |
+ +-------------------------------------+
+ | {"k":1} |
+ +-------------------------------------+
+ ```
+3. `<path>` 不能包含通配符
+ ```sql
+ select json_replace('{"k": 1}', "$.*", 2);
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT] In
this situation, path expressions may not contain the * and ** tokens or an
array range, argument index: 1, row index: 0
+ ```
+4. NULL 参数
+ ```sql
+ select json_replace(NULL, '$[1]', 123);
+ ```
+ ```text
+ +---------------------------------+
+ | json_replace(NULL, '$[1]', 123) |
+ +---------------------------------+
+ | NULL |
+ +---------------------------------+
+ ```
+ ```sql
+ select json_replace('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +---------------------------------------+
+ | json_replace('{"k": "v"}', NULL, 123) |
+ +---------------------------------------+
+ | NULL |
+ +---------------------------------------+
+ ```
+ ```sql
+ select json_replace('{"k": "v"}', '$.k', NULL);
+ ```
+ ```text
+ +-----------------------------------------+
+ | json_replace('{"k": "v"}', '$.k', NULL) |
+ +-----------------------------------------+
+ | {"k":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-set.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
index 115cf7e710d..bd4c47596c0 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-set.md
@@ -6,62 +6,75 @@
---
## 描述
-`json_set` 函数在 JSON 中插入或更新数据并返回结果。
+`JSON_SET` 函数用于在 JSON 中插入或者替换数据并返回结果。
## 语法
```sql
-JSON_SET (<json_str>, <path>, <val> [, <path>, <val>, ...])
+JSON_SET (<json_object>, <path>, <value>[, <path>, <value>, ...])
```
## 参数
-| 参数 | 描述
|
-|-------|-------------------------------------------------------------------------------------------------------------------------|
-| `<jsonStr>` | 要插入的 JSON 对象。可以是任意类型元素的 JSON 对象，包括`NULL`，如果没有指定元素，则返回一个空数组。如果
`json_str` 不是有效的 JSON 或任何 `path` 参数不是有效的路径表达式或包含了 * 通配符，则会返回错误 |
-| `<jsonPath>` | 要插入的 JSON 路径。如果是 `NULL` ，则返回 NULL
|
-| `<val>` | 要插入 JSON 的值。如果是 `NULL` ，则会在对应的位置插入 `NULL` 的 value 值。
|
+- `<json_object>` JSON 类型表达式，被修改的目标。
+- `<path>` String 类型表达式，指定插入值的路径
+- `<value>` JSON 类型或其他 [`TO_JSON`](./to-json.md) 支持的类型，要插入的值。
## 返回值
+- Nullable(JSON) 返回被修改后的 JSON 对象
-`json_set` 函数在 JSON 中插入或更新数据并返回结果。如果 `json_str` 或 `path` 为 NULL，则返回 NULL。否则，如果
`json_str` 不是有效的 JSON 或任何 `path` 参数不是有效的路径表达式或包含了 * 通配符，则会返回错误。
-
-路径值对按从左到右的顺序进行评估。
-
-如果 JSON 中已存在某个路径，则路径值对会将现有 JSON 值覆盖为新值。如果 JSON 中不存在该路径，则路径值对会添加该值到 JSON
中，如果路径标识某个类型的值，则：
-
-* 对于现有对象中不存在的成员，会将新成员添加到该对象中并与新值相关联。
-* 对于现有数组结束后的位置，该数组将扩展为包含新值。如果现有值不是数组，则自动转换为数组，然后再扩展为包含新值的数组。
-
-否则，对于 JSON 中不存在的某个路径的路径值对将被忽略且不会产生任何影响。
+## 使用说明
+1. 当 `<path>` 指向的对象存在时，其行为和 [`JSON_REPLACE`](./json-replace.md) 一致，否则其行为和
[`JSON_INSERT`](./json-insert.md) 一致
## 示例
-
-```sql
-select json_set(null, null, null);
-```
-```text
-+------------------------------+
-| json_set(NULL, NULL, 'NULL') |
-+------------------------------+
-| NULL |
-+------------------------------+
-```
-```sql
-select json_set('{"k": 1}', "$.k", 2);
-```
-```text
-+------------------------------------+
-| json_set('{\"k\": 1}', '$.k', '2') |
-+------------------------------------+
-| {"k":2} |
-+------------------------------------+
-```
-```sql
-select json_set('{"k": 1}', "$.j", 2);
-```
-```text
-+------------------------------------+
-| json_set('{\"k\": 1}', '$.j', '2') |
-+------------------------------------+
-| {"k":1,"j":2} |
-+------------------------------------+
-```
+1. 路径不存在
+ ```sql
+ select json_set('{}', '$.k', json_parse('{}'), '$.k.k2', 123);
+ ```
+ ```text
+ +--------------------------------------------------------+
+ | json_set('{}', '$.k', json_parse('{}'), '$.k.k2', 123) |
+ +--------------------------------------------------------+
+ | {"k":{"k2":123}} |
+ +--------------------------------------------------------+
+ ```
+2. `<path>` 指向的值在 JSON 对象中已经存在
+ ```sql
+ select json_set('{"k": 1}', "$.k", 2);
+ ```
+ ```text
+ +--------------------------------+
+ | json_set('{"k": 1}', "$.k", 2) |
+ +--------------------------------+
+ | {"k":2} |
+ +--------------------------------+
+ ```
+3. NULL 参数
+ ```sql
+ select json_set(NULL, '$[1]', 123);
+ ```
+ ```text
+ +-----------------------------+
+ | json_set(NULL, '$[1]', 123) |
+ +-----------------------------+
+ | NULL |
+ +-----------------------------+
+ ```
+ ```sql
+ select json_set('{"k": "v"}', NULL, 123);
+ ```
+ ```text
+ +-----------------------------------+
+ | json_set('{"k": "v"}', NULL, 123) |
+ +-----------------------------------+
+ | NULL |
+ +-----------------------------------+
+ ```
+ ```sql
+ select json_set('{"k": "v"}', '$.k[1]', NULL);
+ ```
+ ```text
+ +----------------------------------------+
+ | json_set('{"k": "v"}', '$.k[1]', NULL) |
+ +----------------------------------------+
+ | {"k":["v",null]} |
+ +----------------------------------------+
+ ```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
