JSON_OBJECT スカラー関数

JSON_OBJECT 関数は、指定されたキー:値のペアを使用して、JSON オブジェクトを生成します。キー:値のペアを指定しないと、空のオブジェクトが戻されます。

構文図を読む構文図をスキップするJSON_OBJECT(,KEYkey-expressionVALUEJSON-expressionFORMAT JSONBSONNULL ON NULLABSENT ON NULLWITHOUT UNIQUE KEYSWITH UNIQUE KEYSRETURNING CLOB(2G) FORMAT JSONRETURNINGdata-typeFORMAT JSONENCODING UTF8FORMAT BSON)
data-type
構文図を読む構文図をスキップするCHARACTERCHAR(1)( integer)CHARACTERCHARVARYINGVARCHAR( integer)CHARACTERCHARLARGE OBJECTCLOB(1M)( integerKMG)BINARY VARYINGVARBINARY(integer)BINARY LARGE OBJECTBLOB(1M)( integerKMG)

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

key-expression
JSON キーの名前。名前は NULL であってはなりません (SQLSTATE 22004)。key-expression の結果は、以下のデータ・タイプを除く、組み込み文字ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
JSON-expression
key-expression に関連付けた JSON 値を生成するために使用する式。
この式の結果タイプは、どの組み込みデータ・タイプであってもかまいません。ただし、以下のデータ・タイプであってはなりません (SQLSTATE 42815)。
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • BINARY
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
  • XML
  • 上記のデータ・タイプに基づくユーザー定義タイプ

生成される値が数値の場合に、その数値が Infinity、NaN、および sNaN であってはなりません (SQLSTATE 22023)。

FORMAT JSON も FORMAT BSON も指定しなかった場合、生成された値が数値でなければ、結果ストリング内の特殊文字 (例えば、バックスラッシュや二重引用符) はエスケープされます。

FORMAT JSON も FORMAT BSON も指定しなかった場合、バイナリー・ストリング・タイプの式は、FORMAT BSON として解釈されます。

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

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

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

FORMAT BSON
JSON-expression が JSON データの BSON 表現として形式設定されていることを示します (SQLSTATE 22032)。 JSON-expression は、バイナリー・ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。
ON NULL
JSON-expression が NULL 値である場合に何を戻すかを指定します。
NULL ON NULL
NULL 値を表す文字ストリングを戻します。この節がデフォルトです。
ABSENT ON NULL
キー:値のペアを JSON オブジェクトから除外します。
WITHOUT UNIQUE KEYS または WITH UNIQUE KEYS
結果の JSON オブジェクトのキー値をユニークにする必要があるかどうかを指定します。
WITHOUT UNIQUE KEYS
結果の JSON オブジェクトに重複キーがあるかどうかは検査されません。この節がデフォルトです。
WITH UNIQUE KEYS
結果の JSON オブジェクトのキー値はユニークでなければなりません (SQLSTATE 22037)。

ユニーク・キーを持つ JSON オブジェクトを生成することが、ベスト・プラクティスと見なされています。key-expression がユニークなキー名を生成する場合は、WITH UNIQUE KEYS を省いてパフォーマンスを向上させることができます。

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)。

注

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

例

  1. 個人の名前の JSON オブジェクトを生成します。
    VALUES JSON_OBJECT(KEY 'first' VALUE 'John', KEY 'last' VALUE 'Doe')

1
-----------------------------
{"first":"John","last":"Doe"}
  2. 従業員番号が '000020' の従業員の姓、雇用日、給与を含む JSON オブジェクトを生成します。 
    SELECT JSON_OBJECT(KEY 'Last name' VALUE LASTNAME, 
                   KEY 'Hire date' VALUE HIREDATE, 
                   KEY 'Salary' VALUE SALARY)
   FROM EMPLOYEE
   WHERE EMPNO  = '000020';

1
-------------------------------------------------------------------
{"Last name":"THOMPSON","Hire date":"1973-10-10","Salary":41250.00}