MariaDB JSON_ARRAY_APPEND() 函数使用指南
在 MariaDB 中,JSON_ARRAY_APPEND()
是一个内置函数,它向 JSON 文档中的指定的数组中追加一个值并返回修改后的 JSON 文档。
您还可以使用 JSON_ARRAY_INSERT()
将值插入 JSON 数组中。
MariaDB JSON_ARRAY_APPEND()
语法
这里是 MariaDB JSON_ARRAY_APPEND()
的语法:
JSON_ARRAY_APPEND(json, path, value[, path2, value2] ...)
参数
json
- 必需的。被修改的 JSON 文档。
path
- 必需的。添加新元素的路径。一个有效的路径表达式,它不能包含
*
或**
。 value
- 必需的。被添加到数组的新元素值。
返回值
MariaDB JSON_ARRAY_APPEND()
函数用来修改 JSON 文档,它向指定的数组节点中追加一个元素,并返回修改后的 JSON 文档。
如果路径表达式指示的节点不是一个数组节点,JSON_ARRAY_APPEND()
函数将会将此节点的值作为数组的第一个元素,并在数组的尾部追加新元素。
如果 JSON 文档或者路径为 NULL
,此函数将返回 NULL
。
JSON_ARRAY_APPEND()
函数将在以下情况下返回错误:
- 如果参数
json
不是有效的 JSON 文档,MariaDB 将会给出错误。您可以使用JSON_VALID()
验证 JSON 文档的有效性。 - 如果参数
path
不是有效的路径表达式或者其中包含*
或**
, MariaDB 将会给出错误。
MariaDB JSON_ARRAY_APPEND()
示例
这里列出了几个常见的 JSON_ARRAY_APPEND()
用法示例。
追加一个值
SELECT JSON_ARRAY_APPEND('[1, 2, 3]', '$', 4);
输出:
+----------------------------------------+
| JSON_ARRAY_APPEND('[1, 2, 3]', '$', 4) |
+----------------------------------------+
| [1, 2, 3, 4] |
+----------------------------------------+
这里, 路径表达式 $
表示正在操作的 JSON 文档。
追加多个值
可以在对 JSON_ARRAY_APPEND()
的单个调用中追加多个值。
例:
SELECT JSON_ARRAY_APPEND('[1, 2, 3]', '$', 4, '$', 5);
输出:
+------------------------------------------------+
| JSON_ARRAY_APPEND('[1, 2, 3]', '$', 4, '$', 5) |
+------------------------------------------------+
| [1, 2, 3, 4, 5] |
+------------------------------------------------+
向内嵌数组中追加元素
SELECT JSON_ARRAY_APPEND('[1, [2, 3]]', '$[1]', 4);
输出:
+---------------------------------------------+
| JSON_ARRAY_APPEND('[1, [2, 3]]', '$[1]', 4) |
+---------------------------------------------+
| [1, [2, 3, 4]] |
+---------------------------------------------+
这里, 路径表达式 $[1]
表示正在操作的 JSON 文档数组中的第 2 个元素。
向对象中的数组中追加元素
SELECT JSON_ARRAY_APPEND('{"name": "Tim", "hobby": ["car"]}', '$.hobby', "food");
输出:
+---------------------------------------------------------------------------+
| JSON_ARRAY_APPEND('{"name": "Tim", "hobby": ["car"]}', '$.hobby', "food") |
+---------------------------------------------------------------------------+
| {"name": "Tim", "hobby": ["car", "food"]} |
+---------------------------------------------------------------------------+
这里, 路径表达式 $.hobby
表示正在操作的 JSON 文档对象的成员 hobby
。
向非数组中追加值
SELECT JSON_ARRAY_APPEND('1', '$', 2);
输出:
+--------------------------------+
| JSON_ARRAY_APPEND('1', '$', 2) |
+--------------------------------+
| [1, 2] |
+--------------------------------+
这里,JSON 文档有元素 1
修改成了数组 [1, 2]
。
同样可以向数组中的非数组成员中追加,比如:
SELECT JSON_ARRAY_APPEND('[1, 2]', '$[1]', 3);
输出:
+----------------------------------------+
| JSON_ARRAY_APPEND('[1, 2]', '$[1]', 3) |
+----------------------------------------+
| [1, [2, 3]] |
+----------------------------------------+
还可以向对象中的非数组成员中追加,比如:
SELECT JSON_ARRAY_APPEND('{"name": "Tim", "hobby": "car"}', '$.hobby', "food");
输出:
+-------------------------------------------------------------------------+
| JSON_ARRAY_APPEND('{"name": "Tim", "hobby": "car"}', '$.hobby', "food") |
+-------------------------------------------------------------------------+
| {"name": "Tim", "hobby": ["car", "food"]} |
+-------------------------------------------------------------------------+
NULL
参数
如果任意一个参数为 NULL
, MariaDB JSON_ARRAY_APPEND
将返回 NULL
:
SELECT JSON_ARRAY_APPEND(NULL, '$', 0);
输出:
+---------------------------------+
| JSON_ARRAY_APPEND(NULL, '$', 0) |
+---------------------------------+
| NULL |
+---------------------------------+
结论
在 MariaDB 中,JSON_ARRAY_APPEND()
是一个内置函数,它向 JSON 文档中的指定的数组中追加一个值并返回修改后的 JSON 文档。