MariaDB JSON_CONTAINS() 函数使用指南

在 MariaDB 中，JSON_CONTAINS() 是一个内置函数，它检查一个 JSON 文档中是否包含另一个 JSON 文档。

如果您需要检查 JSON 文档中指定的路径下的是否存在数据，请使用 JSON_CONTAINS_PATH() 函数。

MariaDB JSON_CONTAINS() 语法

这里是 MariaDB JSON_CONTAINS() 的语法：

JSON_CONTAINS(target_json, candidate_json)
JSON_CONTAINS(target_json, candidate_json, path)

参数

target_json
必需的。一个 JSON 文档。
candidate_json
必需的。被包含的 JSON 文档。
path
可选的。一个路径表达式。

如果您提供了错误数量的参数，MariaDB 将报告一个错误： ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_CONTAINS'。

返回值

如果在 JSON 文档 target_json 中包含了 JSON 文档 candidate_json，JSON_CONTAINS() 函数将返回 1，否则返回 0。如果提供了 path 参数，则检查由 path 匹配的部分是否包含 candidate_json JSON 文档。

如果存在以下的情况， JSON_CONTAINS() 函数将返回 NULL：

  • 如果 JSON 文档中不存在指定的路径。
  • 如果任意一个参数为 NULL。

JSON_CONTAINS() 函数将在以下情况下返回错误：

  • 如果参数 json 不是有效的 JSON 文档，MySQL 将会给出错误。您可以使用 JSON_VALID() 验证 JSON 文档的有效性。
  • 如果参数 path 不是有效的路径表达式, MariaDB 将会给出错误。

MariaDB JSON_CONTAINS() 示例

这里列出了几个常见的 JSON_CONTAINS() 用法示例。

示例: 数组

SET @json_doc = '[1, 2, {"x": 3}]';

SELECT
  @json_doc AS 'JSON',
  JSON_CONTAINS(@json_doc, '1') AS `1`,
  JSON_CONTAINS(@json_doc, '{"x": 3}') AS `{"x": 3}`,
  JSON_CONTAINS(@json_doc, '3') AS `3`;

输出：

+------------------+------+----------+------+
| JSON             | 1    | {"x": 3} | 3    |
+------------------+------+----------+------+
| [1, 2, {"x": 3}] |    1 |        1 |    0 |
+------------------+------+----------+------+

示例: 指定路径

SET @json_doc = '[1, 2, [3, 4]]';

SELECT
    JSON_CONTAINS(@json_doc, '2'),
    JSON_CONTAINS(@json_doc, '2', '$[2]');

输出：

+-------------------------------+---------------------------------------+
| JSON_CONTAINS(@json_doc, '2') | JSON_CONTAINS(@json_doc, '2', '$[2]') |
+-------------------------------+---------------------------------------+
|                             1 |                                     0 |
+-------------------------------+---------------------------------------+

这里，我们已经在 JSON_CONTAINS('[1, 2, [3, 4]]', '2', '$[2]') 指定了路径表达式 $[2]，它将在 [3, 4] 中搜索 2。 [3, 4] 中没有包含 2， 因此，它返回了 0。

示例: 对象

SET @json_doc = '{"x":1,"y":[1,2]}';

SELECT
  @json_doc AS 'JSON',
  JSON_CONTAINS(@json_doc, '{"x":1}') AS '{"x":1}',
  JSON_CONTAINS(@json_doc, '1', '$.y') AS '1 in $.y';

输出：

+-------------------+---------+----------+
| JSON              | {"x":1} | 1 in $.y |
+-------------------+---------+----------+
| {"x":1,"y":[1,2]} |       1 |        1 |
+-------------------+---------+----------+

NULL 参数

如果任何参数为 NULL，则 MariaDB JSON_CONTAINS() 函数将返回NULL:

SET @json_doc = '{"x":1,"y":[1,2]}';

SELECT
  JSON_CONTAINS(@json_doc, NULL),
  JSON_CONTAINS(NULL, NULL);

输出：

+--------------------------------+---------------------------+
| JSON_CONTAINS(@json_doc, NULL) | JSON_CONTAINS(NULL, NULL) |
+--------------------------------+---------------------------+
|                           NULL |                      NULL |
+--------------------------------+---------------------------+

结论

在 MariaDB 中，JSON_CONTAINS() 是一个内置函数，它检查一个 JSON 文档中是否包含另一个 JSON 文档。