There are several useful functions for creating JSON data. We have already seen two important functions; JSON_ARRAY() that builds a JSON array type and JSON_OBJECT() that builds a JSON object type. This section discusses some of the other functions
Function Description and Use
JSON_STORAGE_FREE() Displays amount of space remaining in a JSON column following a partial update
JSON_STORAGE_SIZE() Displays the storage used by a JSON value
JSON_TABLE() extracts data from a JSON document and returns it as a relational table
JSON_TYPE() returns a utf8mb4 string indicating the type of a JSON value JSON_UNQUOTE() removes quotes from the JSON value and returns the result as a
utf8mb4 string
JSON_VALID() returns 0 or 1 to indicate whether a value is a valid JSON document
Table 3-1. (continued)
Chapter 3 JSON DOCumeNtS
that you can use to help create JSON documents including functions for aggregating, appending, and inserting data in JSON arrays.
The JSON_ARRAYAGG() function is used to create an array of JSON documents from several rows. It can be helpful when you want to summarize data or combine data from several rows. The function takes a column name and combines the JSON data from the rows into a new array. Listing 3-3 shows examples of using the function. This example takes the rows in the table and combines them to form a new array of JSON objects.
Listing 3-3. Using the JSON_ARRAYARG Function
MySQL localhost:33060+ ssl SQL > CREATE TABLE test.favorites (id int AUTO_INCREMENT PRIMARY KEY, preferences JSON);
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > INSERT INTO test.favorites VALUES (NULL, '{"color": "red"}');
Query OK, 1 row affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > INSERT INTO test.favorites VALUES (NULL, '{"color": "blue"}');
Query OK, 1 row affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > INSERT INTO test.favorites VALUES (NULL, '{"color": "purple"}');
Query OK, 1 row affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT * FROM test.favorites;
+----+---+
| id | preferences | +----+---+
| 1 | {"color": "red"} |
| 2 | {"color": "blue"} |
| 3 | {"color": "purple"} | +----+---+
3 rows in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAYAGG(preferences) FROM test.favorites;
98
+---+
| JSON_ARRAYAGG(preferences) | +---+
| [{"color": "red"}, {"color": "blue"}, {"color": "purple"}] | +---+
1 row in set (0.00 sec)
The JSON_ARRAY_APPEND() is an interesting function that allows you to append data to a JSON array either at the end or immediately after a given path expression. The function takes as parameters a JSON array, a path expression, and the value (including a JSON document) to be inserted. Listing 3-4 shows several examples.
Listing 3-4. Using the JSON_ARRAY_APPEND Function
MySQL localhost:33060+ ssl SQL > SET @base = '["apple","pear",{"grape":"
red"},"strawberry"]';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_APPEND(@base, '$',
"banana");
+---+
| JSON_ARRAY_APPEND(@base, '$', "banana") | +---+
| ["apple", "pear", {"grape": "red"}, "strawberry", "banana"] | +---+
1 row in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_APPEND(@base, '$[2].grape', "green");
+---+
| JSON_ARRAY_APPEND(@base, '$[2].grape', "green") | +---+
| ["apple", "pear", {"grape": ["red", "green"]}, "strawberry"] | +---+
1 row in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SET @base = '{"grape":"red"}';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_APPEND(@base, '$', '{"grape":"red"}');
Chapter 3 JSON DOCumeNtS
+---+
| JSON_ARRAY_APPEND(@base, '$', '{"grape":"red"}') | +---+
| [{"grape": "red"}, "{\"grape\":\"red\"}"] | +---+
1 row in set (0.00 sec)
Note that the first example simply adds a new value to the end of the array. The second example changes the value of the key in the JSON object in the third index to an array and adds a new value. This is an interesting by-product of this function. We see this again in the third example where we change a basic JSON object to a JSON array of JSON objects.
The JSON_ARRAY_INSERT() function is similar except it inserts the value before the path expression. The function takes as parameters a JSON array, a path expression, and the value (including a JSON document) to be inserted. When including multiple path expression and value pairs, the effect is cumulative where the function evaluates the first path expression and value applying the next pair to the result, and so on. Listing 3-5 shows some examples using the new function, which are similar to the previous examples. Note that the positions of the data inserted is before the path expression.
Listing 3-5. Using the JSON_ARRAY_INSERT Function
MySQL localhost:33060+ ssl SQL > SET @base = '["apple","pear", {"grape":["red","green"]},"strawberry"]';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_INSERT(@base, '$[0]',
"banana");
+---+
| JSON_ARRAY_INSERT(@base, '$[0]', "banana") | +---+
| ["banana", "apple", "pear", {"grape": ["red", "green"]}, "strawberry"] | +---+
1 row in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_INSERT(@base, '$[2].grape[0]', "white");
100
+---+
| JSON_ARRAY_INSERT(@base, '$[2].grape[0]', "white") | +---+
| ["apple", "pear", {"grape": ["white", "red", "green"]}, "strawberry"] | +---+
1 row in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SET @base = '[{"grape":"red"}]';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_INSERT(@base, '$[0]', '{"grape":"red"}');
+---+
| JSON_ARRAY_INSERT(@base, '$[0]', '{"grape":"red"}') | +---+
| ["{\"grape\":\"red\"}", {"grape": "red"}] | +---+
1 row in set (0.00 sec)
The JSON_INSERT() function is designed to take a JSON document and inserts one or more values at a specified path expression. That is, you can pass pairs of path expression and value at one time. But there is a catch. The path expression in this case must not evaluate to an element in the document. As with the last function, when including multiple path expressions, the effect is cumulative where the function evaluates the first path expression applying the next path expression to the result, and so on. Listing 3-6 shows an example. Note that the third path expression and value is not inserted because the path expression, $[0], evaluates to the first element, apple.
Listing 3-6. Using the JSON_INSERT Function
MySQL localhost:33060+ ssl SQL > SET @base = '["apple","pear",{"grape":[
"red","green"]},"strawberry"]';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_INSERT(@base, '$[9]',
"banana", '$[2].grape[3]', "white", '$[0]', "orange");
Chapter 3 JSON DOCumeNtS
+---+
| JSON_INSERT(@base, '$[9]', "banana", '$[2].grape[3]', "white", '$[0]', "orange") | +---+
| ["apple", "pear", {"grape": ["red", "green", "white"]}, "strawberry", "banana"] | +---+
1 row in set (0.00 sec)
The JSON_MERGE_PATCH() and JSON_MERGE_PRESERVE() functions are designed to take two or more JSON documents and combine them. The JSON_MERGE_PATH() function replaces values for duplicate keys whereas the JSON_MERGE_PRESERVE() preserves the values for duplicate keys. As with the previous function, you can include as many JSON documents as you want. Note how I used this function to build the example JSON document from the earlier examples. Listing 3-7 shows an example using the methods.
Listing 3-7. Using the JSON_MERGE_PATCH and JSON_MERGE_PRESERVE Functions MySQL localhost:33060+ ssl SQL > SELECT JSON_MERGE_
PATCH('["apple","pear"]', '{"grape":["red","green"]}', '["strawberry"]');
+---+
| JSON_MERGE_PATCH('["apple","pear"]', '{"grape":["red","green"]}', '["strawberry"]') |
+---+
| ["strawberry"] | +---+
1 row in set (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_MERGE_PRESERVE('{"grape":["
red","green"]}', '{"grape":["white"]}');
+---+
| JSON_MERGE_PRESERVE('{"grape":["red","green"]}', '{"grape":["white"]}') | +---+
| {"grape": ["red", "green", "white"]} | +---+
1 row in set (0.00 sec)
If any JSON function is passed an invalid parameter, invalid JSON document, or the path expression does not find an element, some functions return null whereas others may return the original JSON document. Listing 3-8 shows an example. In this case, there is no element at position 8 because the array only has 4 elements.
102
Listing 3-8. Using the JSON_ARRAY_APPEND Function
MySQL localhost:33060+ ssl SQL > SET @base = '["apple","pear", {"grape":"red"},"strawberry"]';
Query OK, 0 rows affected (0.00 sec)
MySQL localhost:33060+ ssl SQL > SELECT JSON_ARRAY_APPEND(@base, '$[7]',
"flesh");
+---+
| JSON_ARRAY_APPEND(@base, '$[7]', "flesh") | +---+
| ["apple", "pear", {"grape": "red"}, "strawberry"] | +---+
1 row in set (0.00 sec)
Now let’s see functions that we can use to modify JSON data.