14.17.5 Functions That Return JSON Value Attributes — MySQL 9.2

14.17.5 Функции, возвращающие атрибуты значений JSON

Функции в этом разделе возвращают атрибуты значений JSON.

JSON_DEPTH(json_doc)

Возвращает максимальную глубину документа JSON. Возвращает NULL, если аргумент является NULL. Возникает ошибка, если аргумент не является корректным JSON-документом.

Пустой массив, пустой объект или скалярное значение имеют глубину 1. Непустой массив, содержащий только элементы глубины 1, или непустой объект, содержащий только члены с глубиной 1, имеет глубину 2. В противном случае, глубина JSON-документа больше 2.

mysql> SELECT JSON_DEPTH('{}'), JSON_DEPTH('[]'), JSON_DEPTH('true');
+------------------+------------------+--------------------+
| JSON_DEPTH('{}') | JSON_DEPTH('[]') | JSON_DEPTH('true') |
+------------------+------------------+--------------------+
|                1 |                1 |                  1 |
+------------------+------------------+--------------------+
mysql> SELECT JSON_DEPTH('[10, 20]'), JSON_DEPTH('[[], {}]');
+------------------------+------------------------+
| JSON_DEPTH('[10, 20]') | JSON_DEPTH('[[], {}]') |
+------------------------+------------------------+
|                      2 |                      2 |
+------------------------+------------------------+
mysql> SELECT JSON_DEPTH('[10, {"a": 20}]');
+-------------------------------+
| JSON_DEPTH('[10, {"a": 20}]') |
+-------------------------------+
|                             3 |
+-------------------------------+

JSON_LENGTH(json_doc[, path])

Возвращает длину JSON-документа или, если указан аргумент path, длину значения в документе, определённого этим путём. Возвращает NULL, если любой аргумент является NULL или аргумент path не определяет значение в документе. Возникает ошибка, если аргумент json_doc не является корректным JSON-документом или аргумент path не является корректным выражением пути.

Длина документа определяется следующим образом:
- Длина скаляра равна 1.
- Длина массива равна количеству элементов в массиве.
- Длина объекта равна количеству членов в объекте.
- Длина не учитывает длину вложенных массивов или объектов.
```
mysql> SELECT JSON_LENGTH('[1, 2, {"a": 3}]');
+---------------------------------+
| JSON_LENGTH('[1, 2, {"a": 3}]') |
+---------------------------------+
|                               3 |
+---------------------------------+
mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}');
+-----------------------------------------+
| JSON_LENGTH('{"a": 1, "b": {"c": 30}}') |
+-----------------------------------------+
|                                       2 |
+-----------------------------------------+
mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b');
+------------------------------------------------+
| JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b') |
+------------------------------------------------+
|                                              1 |
+------------------------------------------------+
```
JSON_TYPE(json_val)

Возвращает строку utf8mb4, указывающую тип JSON-значения. Это может быть объект, массив или скалярный тип, как показано здесь:
```
mysql> SET @j = '{"a": [10, true]}';
mysql> SELECT JSON_TYPE(@j);
+---------------+
| JSON_TYPE(@j) |
+---------------+
| OBJECT        |
+---------------+
mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a'));
+------------------------------------+
| JSON_TYPE(JSON_EXTRACT(@j, '$.a')) |
+------------------------------------+
| ARRAY                              |
+------------------------------------+
mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]'));
+---------------------------------------+
| JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]')) |
+---------------------------------------+
| INTEGER                               |
+---------------------------------------+
mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]'));
+---------------------------------------+
| JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]')) |
+---------------------------------------+
| BOOLEAN                               |
+---------------------------------------+
```
JSON_TYPE() возвращает NULL, если аргумент является NULL:
```
mysql> SELECT JSON_TYPE(NULL);
+-----------------+
| JSON_TYPE(NULL) |
+-----------------+
| NULL            |
+-----------------+
```
Возникает ошибка, если аргумент не является корректным JSON-значением:
```
mysql> SELECT JSON_TYPE(1);
ERROR 3146 (22032): Invalid data type for JSON data in argument 1
to function json_type; a JSON string or JSON type is required.
```
Для результата, не являющегося NULL и не являющимся ошибкой, следующий список описывает возможные возвращаемые значения функции JSON_TYPE():
- Чисто JSON-типы:
  - OBJECT: JSON-объекты
  - ARRAY: JSON-массивы
  - BOOLEAN: JSON-литералы true и false
  - NULL: JSON-литерал null
- Числовые типы:
  - INTEGER: MySQL TINYINT, SMALLINT, MEDIUMINT и INT и BIGINT скаляры
  - DOUBLE: MySQL DOUBLE FLOAT скаляры
  - DECIMAL: MySQL DECIMAL и NUMERIC скаляры
- Временные типы:
  - DATETIME: MySQL DATETIME и TIMESTAMP скаляры
  - DATE: MySQL DATE скаляры
  - TIME: MySQL TIME скаляры
- Строковые типы:
  - STRING: MySQL utf8mb3 символьные типы скаляры: CHAR, VARCHAR, TEXT, ENUM и SET
- Бинарные типы:
  - BLOB: MySQL бинарные типы скаляры, включая BINARY, VARBINARY, BLOB и BIT
- Все остальные типы:
  - OPAQUE (сырые биты)

JSON_VALID(val)

Возвращает 0 или 1, чтобы указать, является ли значение корректным JSON. Возвращает NULL, если аргумент является NULL.

mysql> SELECT JSON_VALID('{"a": 1}');
+------------------------+
| JSON_VALID('{"a": 1}') |
+------------------------+
|                      1 |
+------------------------+
mysql> SELECT JSON_VALID('hello'), JSON_VALID('"hello"');
+---------------------+-----------------------+
| JSON_VALID('hello') | JSON_VALID('"hello"') |
+---------------------+-----------------------+
|                   0 |                     1 |
+---------------------+-----------------------+