SQL JSON String Functions
A SQL JSON function allows creation, searching, and modification of JSON data represented as SQL strings. They can be used with any string values that contain valid JSON data types.
In the JSON functions below, all arguments refer to a string, which can be a string literal, table column, or the result of an expression.
The arguments target
, candidate
, and document
must be a valid JSON document consisting of one or more JSON types.
The argument path
must be a valid path expression that consists of an appropriately formatted set of indexes and/or keys.
JSON Types
NuoDB does not implement a dedicated JSON data type. Instead, NuoDB can parse and manipulate JSON documents encoded into SQL strings. Functions and operators manipulating JSON data will decode SQL string literals using the following conventions:
JSON Type | Example |
---|---|
|
"abc" |
|
1234 |
|
true |
|
null |
|
[1,2,3] |
|
{"key":"value"} |
SQL NULL and JSON null are not the same type.
The JSON null type is case-sensitive. The use of lowercase letters are valid. Mixed case or uppercase letters will result in INVALID_JSON_TEXT error.
|
Path Expression
A function argument requiring a path
must have a correctly formatted path
expression depending on the type of JSON structure searched.
If the document is an array, one or more indexes must be provided.
For an object, one or more keys must be provided.
Since arrays and objects allow nesting, you may provide a path containing both keys and indexes.
Where functions require a valid index or key, an index is considered invalid if it exceeds the bounds of the array, and a key is considered invalid if it does not exist within the JSON object.
Wildcards may be used within a path
expression if the JSON function allows it.
If an object key contains white space, it must be enclosed in double-quotes ("). |
Expression Type | Format | Example |
---|---|---|
Index |
$[index1][index2]… |
$[2] |
Key |
$.key1.key2… |
$.year |
Mixed (index and key) |
$.key[index]… |
$.day[4] |
The JSON standard functions JSON_EXISTS, JSON_QUERY, and JSON_VALUE have an optional path mode specifier.
lax
mode is the default.
In this mode, a structural error is converted to an empty SQL JSON sequence.
strict
mode converts a structural error to a hard error.
Expression Mode | Format | Example |
---|---|---|
|
lax $.key1[index1]… |
lax $.year |
|
strict $.key1[index1]… |
strict $.year |
The lax and strict keywords must be lowercase.
|
Get Attribute Function
The function described in the following table returns the attributes of the JSON document.
Function | Description |
---|---|
IS_VALID_JSON( |
Return TRUE if the
|
Create Function
The function described in the following table creates a JSON-type value.
Function | Description |
---|---|
JSON_OBJECT([ |
Returns a correctly formatted JSON object as a SQL string. The object is created from a list of key/value pairs. The list can be empty. An optional An error occurs if there are an odd number of arguments, any key is null, or the FORMAT JSON clause is used with the key argument.
|
Search Functions
The functions in the following table perform search operations on the JSON document.
Function | Description | |||||
---|---|---|---|---|---|---|
JSON_CONTAINS( |
Returns TRUE or FALSE to indicate the presence of the A NULL will be returned if any argument is NULL, or if the An error occurs if
|
|||||
JSON_CONTAINS_PATH( |
Returns TRUE if the For ONE it will return true if at least one path is contained within the Returns NULL if any argument is NULL. An error occurs if the
|
|||||
JSON_EXISTS( |
Returns TRUE if the Returns NULL if any argument is NULL. An error occurs if the The An optional
|
|||||
JSON_EXTRACT( |
Returns JSON data from the Returns NULL if the argument is NULL, all paths do not contain a value, or the
|
|||||
JSON_QUERY( |
Returns JSON data from The There are three optional clauses that can be used WRAPPER, ON EMPTY, and ON ERROR.
An error occurs in the following situations:
|
|||||
JSON_VALUE( |
Returns JSON data from The There are three optional clauses that can be used ON EMPTY, ON ERROR, and RETURNING.
An error occurs in the following situations:
|
Modify Functions
The functions in the following table return a modified result of the input JSON document(s).
Function | Description |
---|---|
JSON_MERGE_PATCH( |
Returns the result of merging two or more JSON documents. The merge will happen two documents at a time moving left to right, obeying the following rules:
|
JSON_UNQUOTE( |
Returns the input
|
More Examples
A few more examples using these JSON functions are given below.
Example 1
IS_VALID_JSON
CREATE TABLE documents(doc STRING CHECK(IS_VALID_JSON(doc)));
INSERT INTO documents VALUES('not valid json');
Error 23001: violation of constraint "DOC"
INSERT INTO documents VALUES('"valid json"');
SELECT * FROM documents;
DOC
------------
"valid json"
Example 2
JSON_MERGE_PATCH
CREATE TABLE records (old STRING, new STRING);
INSERT INTO records VALUES ('{"ID":502,"Owner":"Alice","Status":"Active"}', '{"Owner":"Alice","Status":"Inactive"}');
SELECT JSON_MERGE_PATCH(old, new) AS "Latest Record" FROM records;
Latest records
----------------------------------------------
{"ID":502,"Owner":"Alice","Status":"Inactive"}
Example 3
JSON_CONTAINS
CREATE TABLE exam_results (id INT, name STRING, answer_sheet STRING);
INSERT INTO exam_results VALUES
(12, 'John', '{"Section A":{"Question 2":{"Question":"What is the value of PI?","Answer":3.1415}}, "Section B":{"Question 7":{"Question":"What is the Capital of France?","Answer":"Paris"}}}'),
(34, 'Paul', '{"Section A":{"Question 2":{"Question":"What is the value of PI?","Answer":3.1415}}, "Section B":{"Question 7":{"Question":"What is the Capital of France?","Answer":"Paris"}}}'),
(56, 'George', '{"Section A":{"Question 2":{"Question":"What is the value of PI?","Answer":3.5}}, "Section B":{"Question 7":{"Question":"What is the Capital of France?","Answer":"Paris"}}}'),
(72, 'Ringo', '{"Section A":{"Question 2":{"Question":"What is the value of PI?","Answer":42}}, "Section B":{"Question 7":{"Question":"What is the Capital of France?","Answer":"Rome"}}}');
SELECT id, name FROM exam_results WHERE JSON_CONTAINS(answer_sheet, '3.1415', '$."Section A"."Question 2"."Answer"') = true;
ID NAME
--- -----
12 John
34 Paul
Example 4
JSON_CONTAINS_PATH
SELECT COUNT(*) FROM exam_results WHERE JSON_CONTAINS_PATH(answer_sheet, 'ALL', '$."Section A"."Question 2"."Answer"') = true;
[COUNT]
--------
4
Example 5
JSON_EXTRACT
SELECT name, JSON_EXTRACT(answer_sheet, '$."Section B"."Question 7"."Answer"') AS "Capital of France" FROM exam_results;
NAME Capital of France
------ -----------------
John "Paris"
Paul "Paris"
George "Paris"
Ringo "Rome"
Example 6
JSON_UNQUOTE
SELECT name, JSON_UNQUOTE(JSON_EXTRACT(answer_sheet, '$."Section B"."Question 7"."Answer"')) AS "Capital of France" FROM exam_results;
NAME Capital of France
------ -----------------
John Paris
Paul Paris
George Paris
Ringo Rome
Example 7
JSON_OBJECT
SELECT JSON_OBJECT() FROM dual;
[JSON_OBJECT]
--------------
{}
CREATE TABLE items (id INTEGER, object STRING);
INSERT INTO items VALUES ('101', JSON_OBJECT(1, 55, 2, 7.8, 3, null));
INSERT INTO items VALUES ('102', JSON_OBJECT(4, 'blue', 5, 'green'));
INSERT INTO items VALUES ('103', JSON_OBJECT('North', 'Up', 'South', 'Down'));
INSERT INTO items VALUES ('104', JSON_OBJECT(1, '{"number":1234}' FORMAT JSON));
SELECT * FROM items;
ID OBJECT
--- -----------------------------
101 {"1":55,"2":7.8,"3":null}
102 {"4":"blue","5":"green"}
103 {"North":"Up","South":"Down"}
104 {"1":{"number":1234}}
Example 8
JSON_EXISTS
CREATE TABLE employees (id INTEGER, profile STRING);
INSERT INTO employees VALUES
(101,'{"name":"Alice","age":34,"Department":"HR","Location":"Helsinki","Training":{"First Aid":true}}'),
(102,'{"name":"Bob","age":30,"Department":"HR","Location":"Brussels","Training":{}}'),
(103,'{"name":"Charlie","age":42,"Department":"Finance","Location":"Lisbon","Training":{"First Aid":true}}'),
(104,'{"name":"Diana","Department":"Engineering","Location":"Madrid","Training":{"First Aid":false}}'),
(105,'{"name":"Evan","age":27,"Department":"Engineering","Location":"Paris","Training":{}}'),
(106,'{"name":"Fiona","age":29,"Department":"Engineering","Location":"Paris","Training":{"First Aid":false}}');
SELECT id FROM employees where json_exists(profile, '$.age');
ID
---
101
102
103
105
106
SELECT id FROM employees WHERE JSON_EXISTS(profile, 'strict $.age' UNKNOWN ON ERROR) is NULL;
ID
---
104
SELECT id FROM employees WHERE JSON_EXISTS(profile, 'strict $.*."First Aid"' FALSE ON ERROR);
ID
---
101
103
104
106
Example 9
JSON_VALUE
SELECT JSON_VALUE(profile, '$.age' RETURNING INTEGER) AS Age FROM employees;
AGE
------
34
30
42
<null>
27
29
SELECT JSON_VALUE(profile, 'lax $.Training."First Aid"' RETURNING BOOLEAN DEFAULT 'false' ON EMPTY) AS Complete FROM employees;
COMPLETE
---------
TRUE
FALSE
TRUE
FALSE
FALSE
FALSE
SELECT JSON_VALUE(profile, 'strict $.Training."First Aid"' RETURNING BOOLEAN DEFAULT 'false' ON EMPTY) AS Complete FROM employees;
COMPLETE
---------
TRUE
<null>
TRUE
FALSE
<null>
FALSE
Example 10
JSON_QUERY
SELECT JSON_QUERY(profile, '$.Training') FROM employees;
[JSON_QUERY]
-------------------
{"First Aid":true}
{}
{"First Aid":true}
{"First Aid":false}
{}
{"First Aid":false}
SELECT JSON_QUERY(profile, '$.name' WITH WRAPPER) FROM employees;
[JSON_QUERY]
-------------
["Alice"]
["Bob"]
["Charlie"]
["Diana"]
["Evan"]
["Fiona"]