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 文档。