SQL SERVER 2016: JSON Support
Background on JSON:
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for machines to
parse and generate. It is based on a subset of the JavaScript Programming Language.
JSON is built on two structures:
1. Collection of name/value pairs: In various languages, this is realized as an object, record, struct,
dictionary, hash table, keyed list, or associative array.
An object is an unordered set of name/value pairs. An object begins with {(left brace) and ends
with} (right brace). Each name is followed by: (colon) and the name/value pairs are separated
by, (comma).
1. An ordered list of values: In most languages, this is realized as an array, vector, list, or
sequence.
An array is an ordered collection of values. An array begins with [(left bracket) and ends
with] (right bracket). Values are separated by, (comma).
Exporting data as JSON – FOR JSON
FOR JSON Clause:
JSON
{
{AUTO | PATH}
[
[, ROOT [(‘RootName’)]]
[, INCLUDE_NULL_VALUES]
[, WITHOUT_ARRAY_WRAPPER]
]
}
AUTO | PATH
FOR JSON AUTO clause took the result of the query, automatically formatted it as a JSON document and
finally returned it back to client
FOR JSON PATH clause gives you full control to specify the output format of the JSON data; it lets you
create wrapper objects and nest complex properties.
EXAMPLE:
1. FOR JSON PATH clause for Full Control
In case of FOR JSON PATH clause using “.” Symbol in the column aliases, we can name each
object in the resultant JSON array as shown below:
Using “.” symbol in the column aliases doesn’t have any effect in the resulting JSON output in
case of FOR JSON AUTO as shown below:
INCLUDE_NULL_VALUES
Include null values in the JSON output by specifying the INCLUDE_NULL_VALUES option with
the FOR JSON clause.
EXAMPLE:
Customer table Data:
INCLUDE_NULL_VALUES works with FOR JSON PATH as well as FOR JSON AUTO.
For ID =2 we have Country as NULL.
1. Without INCLUDE_NULL_VALUES:
2. With INCLUDE_NULL_VALUES :
ROOT [('RootName')]
Add a single, top-level element to the JSON output by specifying the ROOT option with the FOR
JSON clause. If you don't specify the ROOT option, the JSON output doesn't have a root element.
EXAMPLE:
We can use the ROOT option in the FOR JSON clause to generate a wrapper object around the
generated JSON output.
In the below example the ROOT option creates a Customers JSON wrapper object around the
generated JSON output:
WITHOUT_ARRAY_WRAPPER
Remove the square brackets that surround the JSON output by default by specifying
the WITHOUT_ARRAY_WRAPPER option with the FOR JSON clause. If you don't specify this
option, the JSON output is enclosed within square brackets. Use the
WITHOUT_ARRAY_WRAPPER option to generate a single JSON object as output.
Transform JSON text to relational table – OPENJSON
OPENJSON is one of the new JSON function introduced in Sql Server 2016, it is very much similar to the
OPENXML function. This table valued function can be used to transform the JSON text to one or many
rows.
Syntax:
OPENJSON( json_string [, json_path ] )
[ WITH (column_mapping_definition1
[,column_mapping_definition2]
[,… column_mapping_definitionN])
]
column_mapping_definition: column name column type [column_json_path] [AS JSON]
Json_string is the JSON string from which will be transformed to row(s).
Json_path is the location of the JSON string in the json_string parameter, which will converted
to one or many rows.
WITH clause: This is an optional clause it can used to explicitly specify the schema of the result.
Each column in the resultant output can be defined by specifying the column name, column
type, it’s location i.e. column json path and the [AS JSON] clause specifies that the column value
will be a JSON object or an array, if it is not specified the expected column value is a scalar value.
RETURNS:
Key: Property name if it is present otherwise it will be index
value: Property value
type: An integer number that represents the type of the value. Next example explains all the
possible type values.
EXAMPLE:
1. Specify the json_path in the OPENJSON function
1. OPENJSON function with explicit schema declaration
In this example the json_path in the OPENJSON function points to the array of the JSON objects.
In the schema declaration columns values json path is not mentioned, in such cases it tries to
match the JSON property name by column name and returns its corresponding JSON property
value.
Built-in functions for JSON processing
JSON built-in functions that are available in SQL Server 2016 are:
ISJSON( jsonText ) :
ISJSON function validates whether the string parameter supplied to it is a valid JSON or not. If supplied
string is a valid JSON then it will return value as 1, otherwise it returns the value 0. In case input is a
NULL then it returns output as NULL.
Example
1. Input is a valid JSON, in this case the ISJSON function will return value as 1
JSON_VALUE (jsonText, path):
JSON_VALUE function returns the scalar value from the input JSON text from the specified JSON path
location. This function will return error in the scenario if the specified json_path is resulting in a JSON
object or array,
EXAMPLE:
1. Basic JSON_VALUE Function
JSON_QUERY ( json_string, json_path )
JSON_QUERY basically returns the JSON fragment (i.e. JSON object or an array) from the input JSON
string from the specified JSON path.This function will return error even in the scenario if the specified
json_path is resulting in a scalar value other than the JSON object or array.
Example
1. Basic JSON_QUERY Function