12.17.5 Functions That Return JSON Value Attributes — MySQL 5.7

12.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 utf8 символьного типа скаляры: CHAR, VARCHAR, TEXT, ENUM и SET
- Бинарные типы:
  - BLOB: MySQL бинарные типы скаляры: BINARY, VARBINARY, BLOB
  - BIT: MySQL 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 |
+---------------------+-----------------------+