14.17.5 Functions That Return JSON Value Attributes — MySQL 8.4

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 |
+---------------------+-----------------------+