forked from docs/doc-exports
Su, Xiaomeng
be9eabe464
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com> Co-authored-by: Su, Xiaomeng <suxiaomeng1@huawei.com> Co-committed-by: Su, Xiaomeng <suxiaomeng1@huawei.com>
230 lines
14 KiB
HTML
230 lines
14 KiB
HTML
<a name="dli_08_15094"></a><a name="dli_08_15094"></a>
|
|
|
|
<h1 class="topictitle1">JSON Functions</h1>
|
|
<div id="body0000001737422536"><p id="dli_08_15094__p12560449165611">JSON functions use JSON path expressions described in the SQL standard ISO/IEC TR 19075-6. Their syntax is inspired by ECMAScript and adopts many of its features, but is neither a subset nor a superset of it.</p>
|
|
<p id="dli_08_15094__p1856084925612">There are two types of path expressions: lax mode and strict mode. When omitted, it defaults to strict mode. Strict mode is intended to check data from a schema perspective and will throw an error when data does not conform to the path expression. However, functions like <strong id="dli_08_15094__b4760132418411">JSON_VALUE</strong> allow for defining fallback behavior when encountering errors. Lax mode, on the other hand, will convert errors to an empty sequence.</p>
|
|
<p id="dli_08_15094__p205601849165612">The special character $ represents the root node in a JSON path. Paths can access properties ($.a), array elements ($.a[0].b), or all elements in an array ($.a[*].b).</p>
|
|
<p id="dli_08_15094__p1656024985619">Known limitations: not all features of lax mode are currently supported correctly.</p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="dli_08_15094__table1662544019117" frame="border" border="1" rules="all"><caption><b>Table 1 </b>JSON functions</caption><thead align="left"><tr id="dli_08_15094__row196259408112"><th align="left" class="cellrowborder" valign="top" width="18.67%" id="mcps1.3.5.2.3.1.1"><p id="dli_08_15094__p262514401511">SQL Function</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="81.33%" id="mcps1.3.5.2.3.1.2"><p id="dli_08_15094__p1762544019115">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="dli_08_15094__row96252401513"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p1662517403113">IS JSON [ { VALUE | SCALAR | ARRAY | OBJECT } ]</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p462584019111">Determines whether a given string is a valid JSON string.</p>
|
|
<p id="dli_08_15094__p22627293217">Specifying an optional type parameter will impose constraints on the allowed types of JSON objects. If the string is a valid JSON but not of that type, it returns <strong id="dli_08_15094__b116901078113">false</strong>. The default value is <strong id="dli_08_15094__b27115261119">VALUE</strong>.</p>
|
|
<pre class="screen" id="dli_08_15094__screen1348716460311">-- TRUE
|
|
'1' IS JSON
|
|
'[]' IS JSON
|
|
'{}' IS JSON
|
|
|
|
-- TRUE
|
|
'"abc"' IS JSON
|
|
-- FALSE
|
|
'abc' IS JSON
|
|
NULL IS JSON
|
|
|
|
-- TRUE
|
|
'1' IS JSON SCALAR
|
|
-- FALSE
|
|
'1' IS JSON ARRAY
|
|
-- FALSE
|
|
'1' IS JSON OBJECT
|
|
|
|
-- FALSE
|
|
'{}' IS JSON SCALAR
|
|
-- FALSE
|
|
'{}' IS JSON ARRAY
|
|
-- TRUE
|
|
'{}' IS JSON OBJECT</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row1662512401412"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p362516401512">JSON_EXISTS(jsonValue, path [ { TRUE | FALSE | UNKNOWN | ERROR } ON ERROR ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p3625240216">Determines whether a JSON string satisfies a given path search condition.</p>
|
|
<p id="dli_08_15094__p1097810441412">If error behavior is ignored, <strong id="dli_08_15094__b1565271511211">FALSE ON ERROR</strong> is the default value.</p>
|
|
<pre class="screen" id="dli_08_15094__screen12219141912515">-- TRUE
|
|
SELECT JSON_EXISTS('{"a": true}', '$.a');
|
|
-- FALSE
|
|
SELECT JSON_EXISTS('{"a": true}', '$.b');
|
|
-- TRUE
|
|
SELECT JSON_EXISTS('{"a": [{ "b": 1 }]}',
|
|
'$.a[0].b');
|
|
|
|
-- TRUE
|
|
SELECT JSON_EXISTS('{"a": true}',
|
|
'strict $.b' TRUE ON ERROR);
|
|
-- FALSE
|
|
SELECT JSON_EXISTS('{"a": true}',
|
|
'strict $.b' FALSE ON ERROR);</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row1462510401411"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p2625940513">JSON_STRING(value)</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p9625840218">Serializes a value to JSON.</p>
|
|
<p id="dli_08_15094__p5180126191414">This function returns a JSON string containing the serialized value. If the value is <strong id="dli_08_15094__b202341311136">NULL</strong>, the function returns <strong id="dli_08_15094__b824215159133">NULL</strong>.</p>
|
|
<pre class="screen" id="dli_08_15094__screen133811576147">-- NULL
|
|
JSON_STRING(CAST(NULL AS INT))
|
|
|
|
-- '1'
|
|
JSON_STRING(1)
|
|
-- 'true'
|
|
JSON_STRING(TRUE)
|
|
-- '"Hello, World!"'
|
|
JSON_STRING('Hello, World!')
|
|
-- '[1,2]'
|
|
JSON_STRING(ARRAY[1, 2])</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row662564020113"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p166251401516">JSON_VALUE(jsonValue, path [RETURNING <dataType>] [ { NULL | ERROR | DEFAULT <defaultExpr> } ON EMPTY ] [ { NULL | ERROR | DEFAULT <defaultExpr> } ON ERROR ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p1862517409117">Extracts a scalar from a JSON string.</p>
|
|
<p id="dli_08_15094__p348817463159">This method searches for the given path expression in the JSON string and returns the value if it is a scalar. If it is not a scalar value, it cannot be returned. By default, the value is returned as a STRING type. The <strong id="dli_08_15094__b314918241302">returnType</strong> can be used to select a different type, supporting the following types:</p>
|
|
<p id="dli_08_15094__p6488164618154">VARCHAR/STRING</p>
|
|
<p id="dli_08_15094__p22201751215">BOOLEAN</p>
|
|
<p id="dli_08_15094__p748811463156">INTEGER</p>
|
|
<p id="dli_08_15094__p1448811468152">DOUBLE</p>
|
|
<p id="dli_08_15094__p15488646131516">For empty path expressions or errors, it can be defined to return null, throw an error, or return a defined default value. If omitted, the default value is <strong id="dli_08_15094__b134713423116">NULL ON EMPTY</strong> or <strong id="dli_08_15094__b366846173112">NULL ON ERROR</strong>. The default value can be a literal or an expression. If the default value itself causes an error, it will execute the error behavior of <strong id="dli_08_15094__b842314783214">ON EMPTY</strong> and <strong id="dli_08_15094__b13590191118325">ON ERROR</strong>.</p>
|
|
<pre class="screen" id="dli_08_15094__screen2083243110274">-- "true"
|
|
JSON_VALUE('{"a": true}', '$.a')
|
|
|
|
-- TRUE
|
|
JSON_VALUE('{"a": true}', '$.a' RETURNING BOOLEAN)
|
|
|
|
-- "false"
|
|
JSON_VALUE('{"a": true}', 'lax $.b'
|
|
DEFAULT FALSE ON EMPTY)
|
|
|
|
-- "false"
|
|
JSON_VALUE('{"a": true}', 'strict $.b'
|
|
DEFAULT FALSE ON ERROR)
|
|
|
|
-- 0.998D
|
|
JSON_VALUE('{"a.b": [0.998,0.996]}','$.["a.b"][0]'
|
|
RETURNING DOUBLE)</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row7625540913"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p146254402115">JSON_QUERY(jsonValue, path [ { WITHOUT | WITH CONDITIONAL | WITH UNCONDITIONAL } [ ARRAY ] WRAPPER ] [ { NULL | EMPTY ARRAY | EMPTY OBJECT | ERROR } ON EMPTY ] [ { NULL | EMPTY ARRAY | EMPTY OBJECT | ERROR } ON ERROR ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p10625640617">Extracts a JSON value from a JSON string.</p>
|
|
<p id="dli_08_15094__p19514952152915">The result is always returned as a <strong id="dli_08_15094__b2420125993211">STRING</strong>. The <strong id="dli_08_15094__b721351183310">RETURNING</strong> clause is currently not supported.</p>
|
|
<p id="dli_08_15094__p539512615316">The <strong id="dli_08_15094__b183294763420">wrappingBehavior</strong> determines whether the extracted value should be wrapped in an array unconditionally or only if the value itself is not an array.</p>
|
|
<p id="dli_08_15094__p439526173119">The <strong id="dli_08_15094__b7145101213418">onEmpty</strong> and <strong id="dli_08_15094__b27973143341">onError</strong> determine the behavior when the path expression is empty or throws an error. By default, <strong id="dli_08_15094__b19824113118344">null</strong> is returned in both cases. Other options are to use an empty array, an empty object, or throw an error.</p>
|
|
<pre class="screen" id="dli_08_15094__screen12710112913217">-- '{ "b": 1 }'
|
|
JSON_QUERY('{ "a": { "b": 1 } }', '$.a')
|
|
-- '[1, 2]'
|
|
JSON_QUERY('[1, 2]', '$')
|
|
-- NULL
|
|
JSON_QUERY(CAST(NULL AS STRING), '$')
|
|
-- '["c1","c2"]'
|
|
JSON_QUERY('{"a":[{"c":"c1"},{"c":"c2"}]}',
|
|
'lax $.a[*].c')
|
|
|
|
-- Wrap result into an array
|
|
-- '[{}]'
|
|
JSON_QUERY('{}', '$' WITH CONDITIONAL ARRAY WRAPPER)
|
|
-- '[1, 2]'
|
|
JSON_QUERY('[1, 2]', '$' WITH CONDITIONAL ARRAY WRAPPER)
|
|
-- '[[1, 2]]'
|
|
JSON_QUERY('[1, 2]', '$' WITH UNCONDITIONAL ARRAY WRAPPER)
|
|
|
|
-- Scalars must be wrapped to be returned
|
|
-- NULL
|
|
JSON_QUERY(1, '$')
|
|
-- '[1]'
|
|
JSON_QUERY(1, '$' WITH CONDITIONAL ARRAY WRAPPER)
|
|
|
|
-- Behavior if path expression is empty / there is an error
|
|
-- '{}'
|
|
JSON_QUERY('{}', 'lax $.invalid' EMPTY OBJECT ON EMPTY)
|
|
-- '[]'
|
|
JSON_QUERY('{}', 'strict $.invalid' EMPTY ARRAY ON ERROR)</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row6625184010117"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p86267401713">JSON_OBJECT([[KEY] key VALUE value]* [ { NULL | ABSENT } ON NULL ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p66268400111">Builds a JSON object string from a list of key-value pairs.</p>
|
|
<p id="dli_08_15094__p215917483463">Note that the keys must be non-null string literals, while the values can be any expression.</p>
|
|
<p id="dli_08_15094__p38794485469">The function returns a JSON string. The <strong id="dli_08_15094__b16953154113516">ON NULL</strong> behavior defines how to handle NULL values. If omitted, the default is <strong id="dli_08_15094__b14471171118367">NULL ON NULL</strong>.</p>
|
|
<p id="dli_08_15094__p13459135614468">Values created from another JSON constructor (JSON_OBJECT, JSON_ARRAY) will be inserted directly instead of being inserted as a string. This allows for building nested JSON structures.</p>
|
|
<pre class="screen" id="dli_08_15094__screen1423861497">-- '{}'
|
|
JSON_OBJECT()
|
|
|
|
-- '{"K1":"V1","K2":"V2"}'
|
|
JSON_OBJECT('K1' VALUE 'V1', 'K2' VALUE 'V2')
|
|
|
|
-- Expressions as values
|
|
JSON_OBJECT('orderNo' VALUE orders.orderId)
|
|
|
|
-- ON NULL
|
|
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) NULL ON NULL) -- '{"K1":null}'
|
|
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) ABSENT ON NULL) -- '{}'
|
|
|
|
-- '{"K1":{"K2":"V"}}'
|
|
JSON_OBJECT(
|
|
KEY 'K1'
|
|
VALUE JSON_OBJECT(
|
|
KEY 'K2'
|
|
VALUE 'V'
|
|
)
|
|
)</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row136261940319"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p1626040114">JSON_OBJECTAGG([KEY] key VALUE value [ { NULL | ABSENT } ON NULL ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p235214171627">Builds a JSON object string by aggregating key-value expressions into a single JSON object.</p>
|
|
<p id="dli_08_15094__p17352131712215">The key expression must return a non-null string. The value expression can be anything, including other JSON functions. If the value is NULL, the <strong id="dli_08_15094__b29965231370">ON NULL</strong> behavior defines what to do. If omitted, the default is <strong id="dli_08_15094__b0842616203616">NULL ON NULL</strong>.</p>
|
|
<p id="dli_08_15094__p1935271716211">Note that keys must be unique. If a key appears multiple times, an error will be thrown.</p>
|
|
<p id="dli_08_15094__p8352717426">This feature is currently not supported in OVER windows.</p>
|
|
<pre class="screen" id="dli_08_15094__screen31040281455">-- '{"Apple":2,"Banana":17,"Orange":0}'
|
|
SELECT
|
|
JSON_OBJECTAGG(KEY product VALUE cnt)
|
|
FROM orders</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row1962620403120"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p0626340710">JSON_ARRAY([value]* [ { NULL | ABSENT } ON NULL ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p206263401416">Builds a JSON array string from a list of values.</p>
|
|
<p id="dli_08_15094__p5341155211514">The function returns a JSON string. These values can be any expression. The <strong id="dli_08_15094__b178981725369">ON NULL</strong> behavior defines how to handle NULL values. If omitted, the default is <strong id="dli_08_15094__b155214223919">ABSENT ON NULL</strong>.</p>
|
|
<p id="dli_08_15094__p1852215141968">Elements created from another JSON constructor (JSON_OBJECT, JSON_ARRAY) will be inserted directly instead of being inserted as a string. This allows for building nested JSON structures.</p>
|
|
<pre class="screen" id="dli_08_15094__screen183213498611">-- '[]'
|
|
JSON_ARRAY()
|
|
-- '[1,"2"]'
|
|
JSON_ARRAY(1, '2')
|
|
|
|
-- Expressions as values
|
|
JSON_ARRAY(orders.orderId)
|
|
|
|
-- ON NULL
|
|
JSON_ARRAY(CAST(NULL AS STRING) NULL ON NULL) -- '[null]'
|
|
JSON_ARRAY(CAST(NULL AS STRING) ABSENT ON NULL) -- '[]'
|
|
|
|
-- '[[1]]'
|
|
JSON_ARRAY(JSON_ARRAY(1))</pre>
|
|
</td>
|
|
</tr>
|
|
<tr id="dli_08_15094__row425553214515"><td class="cellrowborder" valign="top" width="18.67%" headers="mcps1.3.5.2.3.1.1 "><p id="dli_08_15094__p112551532358">JSON_ARRAYAGG(items [ { NULL | ABSENT } ON NULL ])</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.33%" headers="mcps1.3.5.2.3.1.2 "><p id="dli_08_15094__p121504344716">Builds a JSON object string by aggregating elements into an array.</p>
|
|
<p id="dli_08_15094__p415019341574">The element expression can be anything, including other JSON functions. If the value is NULL, the <strong id="dli_08_15094__b123321429113714">ON NULL</strong> behavior defines what to do. If omitted, the default is <strong id="dli_08_15094__b2098716617393">ABSENT ON NULL</strong>.</p>
|
|
<p id="dli_08_15094__p171501341470">This feature is currently not supported in OVER windows, unbounded session windows, or hop windows.</p>
|
|
<pre class="screen" id="dli_08_15094__screen1424784610811">-- '["Apple","Banana","Orange"]'
|
|
SELECT
|
|
JSON_ARRAYAGG(product)
|
|
FROM orders</pre>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="dli_08_15085.html">Built-In Functions</a></div>
|
|
</div>
|
|
</div>
|
|
|