12.17.6 JSON Utility Functions — MySQL 5.7

12.17.6 Функции для работы с JSON

В этом разделе описываются служебные функции, которые действуют над значениями JSON или строками, которые могут быть распарсены как значения JSON. JSON_PRETTY() выводит значение JSON в формате, удобном для чтения. JSON_STORAGE_SIZE() показывает объем дискового пространства, используемого заданным значением JSON.

JSON_PRETTY(json_val)

Обеспечивает красивую распечатку значений JSON, аналогичную той, что реализована в PHP и других языках и системах баз данных. Предоставляемое значение должно быть значением JSON или допустимым строковым представлением значения JSON. Лишние пробелы и новые строки в этом значении не влияют на вывод. Для NULL значения функция возвращает NULL. Если значение не является документом JSON или не может быть распарсено как таковой, функция завершается с ошибкой.

Форматирование вывода этой функции соответствует следующим правилам:
- Каждый элемент массива или член объекта отображается на отдельной строке, с отступом на один уровень по сравнению с родительским элементом.
- Каждый уровень отступа добавляет два пробела.
- Запятая, разделяющая отдельные элементы массива или члены объекта, печатается перед новой строкой, которая разделяет два элемента или члена.
- Ключ и значение члена объекта разделены двоеточием и пробелом (': ').
- Пустой объект или массив выводится на одной строке. Пробел не печатается между открывающей и закрывающей фигурной скобкой.
- Специальные символы в строковых скалярных значениях и именах ключей экранируются по тем же правилам, которые используются функцией JSON_QUOTE().
```
mysql> SELECT JSON_PRETTY('123'); # scalar
+--------------------+
| JSON_PRETTY('123') |
+--------------------+
| 123                |
+--------------------+

mysql> SELECT JSON_PRETTY("[1,3,5]"); # array
+------------------------+
| JSON_PRETTY("[1,3,5]") |
+------------------------+
| [
  1,
  3,
  5
]      |
+------------------------+

mysql> SELECT JSON_PRETTY('{"a":"10","b":"15","x":"25"}'); # object
+---------------------------------------------+
| JSON_PRETTY('{"a":"10","b":"15","x":"25"}') |
+---------------------------------------------+
| {
  "a": "10",
  "b": "15",
  "x": "25"
}   |
+---------------------------------------------+

mysql> SELECT JSON_PRETTY('["a",1,{"key1":
     >    "value1"},"5",     "77" ,
     >       {"key2":["value3","valueX",
     > "valueY"]},"j", "2"   ]')\G  # nested arrays and objects
*************************** 1. row ***************************
JSON_PRETTY('["a",1,{"key1":
             "value1"},"5",     "77" ,
                {"key2":["value3","valuex",
          "valuey"]},"j", "2"   ]'): [
  "a",
  1,
  {
    "key1": "value1"
  },
  "5",
  "77",
  {
    "key2": [
      "value3",
      "valuex",
      "valuey"
    ]
  },
  "j",
  "2"
]
```
Добавлена в MySQL 5.7.22.

JSON_STORAGE_SIZE(json_val)

Эта функция возвращает количество байтов, используемых для хранения двоичного представления документа JSON. Когда аргумент является JSON столбцом, это пространство, используемое для хранения документа JSON. json_val должен быть допустимым документом JSON или строкой, которая может быть распарсена как таковой. В случае, если это строка, функция возвращает количество занимаемого места в двоичном представлении JSON, созданном путём парсинга строки как JSON и преобразования её в двоичный формат. Она возвращает NULL, если аргумент является NULL.

Возникает ошибка, если json_val не является NULL и не является — или не может быть успешно распарсено как — документом JSON.

Чтобы проиллюстрировать поведение этой функции при использовании её с JSON столбцом в качестве аргумента, создадим таблицу с именем jtable, содержащую JSON столбец jcol, вставим значение JSON в таблицу, а затем получим занимаемое этим столбцом пространство с помощью JSON_STORAGE_SIZE(), как показано ниже:

mysql> CREATE TABLE jtable (jcol JSON);
Query OK, 0 rows affected (0.42 sec)

mysql> INSERT INTO jtable VALUES
    ->     ('{"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"}');
Query OK, 1 row affected (0.04 sec)

mysql> SELECT
    ->     jcol,
    ->     JSON_STORAGE_SIZE(jcol) AS Size
    -> FROM jtable;
+-----------------------------------------------+------+
| jcol                                          | Size |
+-----------------------------------------------+------+
| {"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"} |   47 |
+-----------------------------------------------+------+
1 row in set (0.00 sec)

Согласно выводу JSON_STORAGE_SIZE(), вставленный в столбец документ JSON занимает 47 байт. После обновления функция показывает занимаемое пространство для нового значения:

mysql> UPDATE jtable
mysql>     SET jcol = '{"a": 4.55, "b": "wxyz", "c": "[true, false]"}';
Query OK, 1 row affected (0.04 sec)
Rows matched: 1  Changed: 1  Warnings: 0

mysql> SELECT
    ->     jcol,
    ->     JSON_STORAGE_SIZE(jcol) AS Size
    -> FROM jtable;
+------------------------------------------------+------+
| jcol                                           | Size |
+------------------------------------------------+------+
| {"a": 4.55, "b": "wxyz", "c": "[true, false]"} |   56 |
+------------------------------------------------+------+
1 row in set (0.00 sec)

Эта функция также показывает занимаемое пространство для хранения документа JSON в переменной пользователя:

mysql> SET @j = '[100, "sakila", [1, 3, 5], 425.05]';
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
+------------------------------------+------+
| @j                                 | Size |
+------------------------------------+------+
| [100, "sakila", [1, 3, 5], 425.05] |   45 |
+------------------------------------+------+
1 row in set (0.00 sec)

mysql> SET @j = JSON_SET(@j, '$[1]', "json");
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
+----------------------------------+------+
| @j                               | Size |
+----------------------------------+------+
| [100, "json", [1, 3, 5], 425.05] |   43 |
+----------------------------------+------+
1 row in set (0.00 sec)

mysql> SET @j = JSON_SET(@j, '$[2][0]', JSON_ARRAY(10, 20, 30));
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
+---------------------------------------------+------+
| @j                                          | Size |
+---------------------------------------------+------+
| [100, "json", [[10, 20, 30], 3, 5], 425.05] |   56 |
+---------------------------------------------+------+
1 row in set (0.00 sec)

Для JSON-литерала эта функция также возвращает занимаемое пространство, как показано ниже:

mysql> SELECT
    ->     JSON_STORAGE_SIZE('[100, "sakila", [1, 3, 5], 425.05]') AS A,
    ->     JSON_STORAGE_SIZE('{"a": 1000, "b": "a", "c": "[1, 3, 5, 7]"}') AS B,
    ->     JSON_STORAGE_SIZE('{"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"}') AS C,
    ->     JSON_STORAGE_SIZE('[100, "json", [[10, 20, 30], 3, 5], 425.05]') AS D;
+----+----+----+----+
| A  | B  | C  | D  |
+----+----+----+----+
| 45 | 44 | 47 | 56 |
+----+----+----+----+
1 row in set (0.00 sec)

Эта функция была добавлена в MySQL 5.7.22.