JSON_QUERY 関数は、SQL/JSON パス式を使用して、指定された JSON テキストの SQL/JSON 値を戻します。
>>-JSON_QUERY--(--JSON-expression--+-------------+-------------->
+-FORMAT JSON-+
'-FORMAT BSON-'
>--,--sql-json-path-expression--+---------------+--------------->
'-AS--path-name-'
.-RETURNING--CLOB (2G) CCSID 1208--FORMAT JSON--------------.
>--+-----------------------------------------------------------+-->
| .-FORMAT JSON--+----------------+-. |
| | +-ENCODING UTF8--+ | |
| | '-ENCODING UTF16 ' | |
'-RETURNING--data-type--+---------------------------------+-'
'-FORMAT BSON---------------------'
.-ARRAY-.
.-WITHOUT--+-------+--WRAPPER-----------------.
>--+---------------------------------------------+-------------->
| .-UNCONDITIONAL-. .-ARRAY-. |
'-WITH--+---------------+--+-------+--WRAPPER-'
'-CONDITIONAL---'
.-ON SCALAR STRING-.
.-KEEP QUOTES--+------------------+-.
>--+-----------------------------------+------------------------>
| .-ON SCALAR STRING-. |
'-OMIT QUOTES--+------------------+-'
.-NULL ON EMPTY--------------.
>--+----------------------------+------------------------------->
'-+-ERROR--------+--ON EMPTY-'
+-EMPTY ARRAY--+
'-EMPTY OBJECT-'
.-NULL ON ERROR--------------.
>--+----------------------------+--)---------------------------><
'-+-ERROR--------+--ON ERROR-'
+-EMPTY ARRAY--+
'-EMPTY OBJECT-'
data-type
.-(--1--)-------.
|--+-+-+-+-CHARACTER-+--+---------------+----------+--+----------------+---------------------+------------+--|
| | | '-CHAR------' '-(--integer--)-' | +-FOR SBCS DATA--+ | |
| | '-+-+-CHARACTER-+--VARYING-+--(--integer--)-' +-FOR MIXED DATA-+ | |
| | | '-CHAR------' | '-ccsid-clause---' | |
| | '-VARCHAR----------------' | |
| | .-(--1M--)-------------. | |
| '-----+-+-CHARACTER-+--LARGE OBJECT-+------+----------------------+--+----------------+-' |
| | '-CHAR------' | '-(--integer--+---+--)-' +-FOR SBCS DATA--+ |
| '-CLOB------------------------' +-K-+ +-FOR MIXED DATA-+ |
| +-M-+ '-ccsid-clause---' |
| '-G-' |
| .-(--1--)-------. |
+-+---GRAPHIC----+---------------+-------+--+--------------+-------------------------------------------+
| | '-(--integer--)-' | '-ccsid-clause-' |
| +-+-GRAPHIC VARYING-+--(--integer--)---+ |
| | '-VARGRAPHIC------' | |
| | .-(--1M--)-------------. | |
| '---DBCLOB----+----------------------+-' |
| '-(--integer--+---+--)-' |
| +-K-+ |
| +-M-+ |
| '-G-' |
| .-(--1--)-------. |
+-+-+-+-NATIONAL CHARACTER-+--+---------------+----------+---------------------+--+------------------+-+
| | | +-NATIONAL CHAR------+ '-(--integer--)-' | | '-normalize-clause-' |
| | | '-NCHAR--------------' | | |
| | '-+-+-NATIONAL CHARACTER-+--VARYING-+--(--integer--)-' | |
| | | +-NATIONAL CHAR------+ | | |
| | | '-NCHAR--------------' | | |
| | '-NVARCHAR------------------------' | |
| | .-(--1M--)-------------. | |
| '-----+-+-NATIONAL CHARACTER-+--LARGE OBJECT-+------+----------------------+-' |
| | '-NCHAR--------------' | '-(--integer--+---+--)-' |
| '-NCLOB--------------------------------' +-K-+ |
| +-M-+ |
| '-G-' |
| .-(--1--)-------. |
'-+-+-BINARY--+---------------+---------+-----------------+--------------------------------------------'
| | '-(--integer--)-' | |
| '-+-BINARY VARYING-+--(--integer--)-' |
| '-VARBINARY------' |
| .-(--1M--)-------------. |
'---+-BINARY LARGE OBJECT-+----+----------------------+-'
'-BLOB----------------' '-(--integer--+---+--)-'
+-K-+
+-M-+
'-G-'
ccsid-clause
|--CCSID--integer--+------------------+-------------------------|
'-normalize-clause-'
normalize-clause
.-NOT NORMALIZED-.
|--+----------------+-------------------------------------------|
'-NORMALIZED-----'
- JSON-expression
- 組み込みストリング・データ・タイプの値を戻す式。文字またはグラフィックの値が戻される場合は、正しい形式の JSON データが含まれている必要があります。バイナリー・データ・タイプの場合は、明示的または暗黙的な FORMAT 節に従って解釈されます。
- FORMAT JSON または FORMAT BSON
- JSON-expression の解釈方法を指定します。
- FORMAT JSON
- JSON-expression には JSON データが含まれています。JSON-expression がバイナリー・データの場合、データは UTF-8 または UTF-16 として解釈されます。EBCDIC CCSID を使用してバイナリー・データをエンコードすることはできません。
- FORMAT BSON
- JSON-expression には、JSON データの BSON 表現が含まれています。FORMAT BSON を指定した場合、JSON-expression はバイナリー・ストリング・データ・タイプでなければなりません。
FORMAT 節を指定しなかった場合、JSON-expression が文字ストリングまたはグラフィック・ストリングであれば、JSON-expression は JSON として扱われます。
JSON-expression がバイナリー・ストリングの場合、JSON-expression は BSON として扱われます。
- sql-json-path-expression
- 組み込み文字またはグラフィック・ストリング・データ・タイプの値を戻す式。このストリングは SQL/JSON パス式として解釈され、JSON-expression で指定された JSON データ内で JSON 値を見つけるために使用されます。複数の値のキーが同じ場合、いずれかの JSON 値が選択されます。
- SQL/JSON パス式の内容については、sql-json-path-expressionを参照してください。
- AS path-name
- sql-json-path-expression の識別に使用する名前を指定します。
- RETURNING data-type
- 結果の形式を指定します。
- data-type
- 結果のデータ・タイプです。CHAR 結果および VARCHAR 結果の場合、CCSID を 65535 にすることはできません。デフォルトは CLOB(2G) CCSID 1208 です。
CCSID が指定され、data-type が GRAPHIC、VARGRAPHIC、または DBCLOB の場合、CCSID は Unicode CCSID であることが必要です。
CCSID 属性が指定されないと、CCSID は CAST の指定に記されているように決定されます。
- FORMAT JSON
- JSON データは JSON ストリングとして戻されます。
- ENCODING UTF8 または ENCODING UTF16
- data-type がバイナリー・ストリング・タイプの場合に使用するエンコード方式。この節は、バイナリー・ストリング・タイプの場合にのみ使用できます。バイナリー・ストリングのデフォルトは UTF8 です。
- FORMAT BSON
- JSON データは、BSON 形式で戻されます。FORMAT BSON を指定した場合、data-type は VARBINARY または BLOB ストリング・タイプでなければなりません。FORMAT BSON は、SQL/JSON オブジェクトが戻される場合にのみ使用できます。
- WITHOUT ARRAY WRAPPER または WITH ARRAY WRAPPER
- JSON 配列内で出力値をラップするかどうかを指定する必要があります。
- WITHOUT ARRAY WRAPPER
- 結果をラップしません。これはデフォルトです。複数の SQL/JSON エレメントを含むシーケンスになる SQL/JSON パスを使用すると、エラーになります。
- WITH UNCONDITIONAL ARRAY WRAPPER
- 結果を大括弧で囲んで、JSON 配列を作成します。
- WITH CONDITIONAL ARRAY WRAPPER
- 複数の SQL/JSON エレメントが戻される場合、または JSON 配列でも JSON オブジェクトでもない単一の SQL/JSON エレメントが戻される場合、
結果を大括弧で囲んで、JSON 配列を作成します。
以下の表は、JSON テキスト {a:"10", b:[1, 2]} にこれらの各オプションがどのように適用されるかを示しています。表 1. 各 WRAPPER 節を使用した結果| WRAPPER 文節 |
$.a のパス値 |
$.b のパス値 |
|---|
| WITHOUT ARRAY WRAPPER |
"10" |
[1,2] |
| WITH UNCONDITIONAL ARRAY WRAPPER |
["10"] |
[[1,2]] |
| WITH CONDITIONAL ARRAY WRAPPER |
["10"] |
[1,2] |
- KEEP QUOTES または OMIT QUOTES
- スカラー・ストリングが戻された場合に、周囲の引用符を除去する必要があるかどうかを指定します。
- KEEP QUOTES
- 引用符がスカラー・ストリングから除去されないことを示します。これはデフォルトです。
- OMIT QUOTES
- 引用符がスカラー・ストリングから除去されることを示します。OMIT QUOTES を指定した場合、WITH ARRAY WRAPPER 節は指定できません。
- ON EMPTY
- sql-json-path-expression を使用して空シーケンスが戻された場合の動作を指定します。
- NULL ON EMPTY
- NULL 値が戻されます。これはデフォルトです。
- ERROR ON EMPTY
- エラーが戻されます。
- EMPTY ARRAY ON EMPTY
- 空の配列が戻されます。
- EMPTY OBJECT ON EMPTY
- 空のオブジェクトが戻されます。
- ON ERROR
- JSON_QUERY でエラーが発生した場合の動作を指定します。
- NULL ON ERROR
- NULL 値が戻されます。これはデフォルトです。
- ERROR ON ERROR
- エラーが戻されます。
- EMPTY ARRAY ON ERROR
- 空の配列が戻されます。
- EMPTY OBJECT ON ERROR
- 空のオブジェクトが戻されます。
結果が、NULL になることもあります。JSON-expression が NULL の場合、結果は NULL 値になります。
例
- JSON テキストから、name キーに関連付けられている JSON オブジェクトを返します。
VALUES JSON_QUERY('{"id":"701", "name":{"first":"John", "last":"Doe"}}', '$.name');
この結果、JSON オブジェクトを表す以下のストリングが返されます。{"first":"John", "last":"Doe"}