JSON_VALUE スカラー関数

JSON_VALUE 関数は、SQL/JSON パス式を使用して、JSON テキストから SQL スカラー値を戻します。

構文図を読む構文図をスキップするJSON_VALUE(JSON-expression FORMAT JSONFORMAT BSON,sql-json-path-expression ASpath-nameRETURNING CLOB(2G)RETURNINGdata-type NULL ON EMPTYERRORDEFAULTdefault-expressionON EMPTY NULL ON ERRORERRORDEFAULTdefault-expressionON ERROR)
data-type
構文図を読む構文図をスキップするSMALLINTINTEGERINTBIGINTDECIMALDECNUMERICNUM(5,0)( precision-integer,0, scale-integer)FLOAT(53)( integer)REALDOUBLEPRECISIONDECFLOAT(34)(16)CHARACTERCHAR(1)( integer)CHARACTERCHARVARYINGVARCHAR( integer)CHARACTERCHARLARGE OBJECTCLOB(1M)( integerKMG)BINARY VARYINGVARBINARY(integer)BINARY LARGE OBJECTBLOB(1M)( integerKMG)DATETIMETIMESTAMP(6)(integer)

この関数のスキーマは 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
結果のデータ・タイプを指定します。デフォルトは CLOB (2 GB) です。data-type がバイナリー・ストリング・タイプである場合に使用されるデフォルトのエンコード方式は、UTF-8 です。

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

ON EMPTY
空シーケンスが sql-json-path-expression から戻された場合の動作を指定します。
NULL ON EMPTY
NULL 値が戻されます。この節がデフォルトです。
ERROR ON EMPTY
エラーが戻されます。
DEFAULT default-expression ON EMPTY
default-expression で指定された値が戻されます。default-expression のデータ・タイプは、戻りデータ・タイプと同じでなければなりません (SQLSTATE 42815)。
ON ERROR
JSON_VALUE でエラーが発生した場合の動作を指定します。
NULL ON ERROR
NULL 値が戻されます。この節がデフォルトです。
ERROR ON ERROR
エラーが戻されます。
DEFAULT default-expression ON ERROR
default-expression で指定された値が戻されます。default-expression のデータ・タイプは、戻りデータ・タイプと同じでなければなりません (SQLSTATE 42815)。

結果は NULL になる場合があります。JSON-expression が NULL の場合、結果は NULL 値です。

注

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

例

  1. JSON テキストから値を整数として戻します。 
    VALUES (JSON_VALUE('{"id":"987"}', 'strict $.id' RETURNING INTEGER));

    結果は、987 になります。

  2. JSON テキストから、bonus フィールドの値を取得します。それを整数として戻します。 
    VALUES (JSON_VALUE('{"pay":{"salary":94250.00,"bonus":800.00,"comm":3300.00}}', 
                   'strict $.pay.bonus' RETURNING INTEGER));
    結果は、800 になります。