JSON_QUERY スカラー関数

JSON_QUERY 関数は、SQL/JSON パス式を使用して、指定された JSON テキストの SQL/JSON 値を戻します。

構文図を読む構文図をスキップする JSON_QUERY(JSON-expressionFORMAT JSONFORMAT BSON, sql-json-path-expression ASpath-name RETURNING CLOB(2G) FORMAT JSONRETURNINGdata-typeFORMAT JSONENCODING UTF8FORMAT BSON WITHOUTARRAYWRAPPERWITHUNCONDITIONALCONDITIONALARRAYWRAPPER KEEP QUOTESON SCALAR STRINGOMIT QUOTESON SCALAR STRING NULL ON EMPTYERROREMPTY ARRAYEMPTY OBJECTON EMPTYNULL ON ERRORERROREMPTY ARRAYEMPTY OBJECTON ERROR)
data-type
構文図を読む構文図をスキップするCHARACTERCHAR(1)( integer)CHARACTERCHARVARYINGVARCHAR( integer)CHARACTERCHARLARGE OBJECTCLOB(1M)( integerKMG)BINARY VARYINGVARBINARY(integer)BINARY LARGE OBJECTBLOB(1M)( integerKMG)

この関数のスキーマは SYSIBM ですが、この関数を修飾名で指定することはできません。

JSON-expression
以下のデータ・タイプを除く、組み込みストリング・データ・タイプである値を戻す式 (SQLSTATE 42815)。
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • BINARY
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
  • 上記のデータ・タイプに基づくユーザー定義タイプ

文字値が戻される場合は、正しい形式の JSON データが含まれている必要があります (SQLSTATE 22032)。 バイナリー・データ・タイプが戻される場合は、明示的または暗黙的な FORMAT 節に従って解釈されます。

FORMAT JSON
JSON-expression は JSON データとして形式設定されています。

JSON-expression が文字ストリング・データ・タイプであれば、JSON データとして扱われます。

バイナリー・ストリング・データ・タイプの JSON-expression は、UTF-8 データとして解釈されます。

FORMAT BSON
JSON-expression が JSON データの BSON 表現として形式設定されていることを示します (SQLSTATE 22032)。 JSON-expression は、バイナリー・ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。
sql-json-path-expression
組み込み文字ストリング・データ・タイプの値を戻す式。このストリングは SQL/JSON パス式として解釈され、JSON-expression で指定された JSON データ内で JSON 値を見つけるために使用されます。SQL/JSON パス式について詳しくは、sql-json-path-expressionを参照してください。
AS path-name
sql-json-path-expression の識別に使用する名前を指定します。
RETURNING data-type
結果のデータ・タイプは、CHAR、VARCHAR、CLOB、VARBINARY、または BLOB にすることができます (SQLSTATE 42815)。デフォルトは CLOB (2 GB) です。

組み込みデータ・タイプの説明については、CREATE TABLE ステートメントを参照してください。

FORMAT JSON
戻されるデータは、JSON データとして形式設定されます。
ENCODING UTF8
data-type がバイナリー・ストリング・タイプの場合に使用するエンコード方式を指定します。 この節は、バイナリー・ストリング・タイプの場合にのみ使用できます。バイナリー・ストリングのデフォルトは UTF-8 です。
FORMAT BSON
戻されるデータは、JSON データの BSON 表現として形式設定されます (SQLSTATE 22032)。 data-type は、バイナリー・ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。
WITHOUT ARRAY WRAPPER または WITH ARRAY WRAPPER
JSON 配列内で出力値をラップするかどうかを指定します。
WITHOUT ARRAY WRAPPER
結果をラップしません。この節がデフォルトです。複数の SQL/JSON エレメントを含むシーケンスに解決される厳密 (strict) な SQL/JSON パス定義を使用すると、エラーになります (SQLSTATE 2203A)。 複数の SQL/JSON エレメントを含むシーケンスに解決される寛容 (lax) な SQL/JSON パス定義を ON EMPTY を指定して使用すると、エラーになります (SQLSTATE 22035)。
WITH UNCONDITIONAL ARRAY WRAPPER
結果を大括弧で囲んで、JSON 配列を作成します。
WITH CONDITIONAL ARRAY WRAPPER
以下の状況の場合に、結果を大括弧で囲んで JSON 配列を作成することを示します。
  • 複数の SQL/JSON エレメントが戻される。
  • JSON 配列でも JSON オブジェクトでもない単一の SQL/JSON エレメントが戻される。
KEEP QUOTES または OMIT QUOTES
スカラー・ストリングが戻された場合に、周囲の引用符を除去する必要があるかどうかを指定します。
KEEP QUOTES
スカラー・ストリングから引用符は除去されません。この節がデフォルトです。
OMIT QUOTES
スカラー・ストリングから引用符が除去されます。OMIT QUOTES を指定した場合、WITH ARRAY WRAPPER 節は指定できません (SQLSTATE 42601)。
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 値です。

注

  • パラメーター・マーカーが、サポートされるデータ・タイプに明示的にキャストされない場合は、エラーが戻されます (SQLSTATE 42815)。

例

  1. JSON テキストから、名前キーに関連付けられている JSON オブジェクトを返します。 
    VALUES JSON_QUERY('{"id":"701", "name":{"first":"John", "last":"Doe"}}', '$.name');
    この結果、JSON オブジェクトを表す以下のストリングが返されます。 
    {"first":"John", "last":"Doe"}

JSON_QUERY のさまざまな配列ラッパー・オプションについては、sql-json-path-expression の例を参照してください。