JSON_OBJECT スカラー関数

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

Read syntax diagramSkip visual syntax diagramJSON_OBJECT(,KEYkey-expressionVALUEJSON-expressionFORMATJSONBSONNULL ON NULLABSENT ON NULLWITHOUT UNIQUE KEYSWITH UNIQUE KEYSRETURNING CLOB(2G) FORMAT JSONRETURNINGdata-typeFORMAT JSONENCODING UTF8FORMAT BSON)
data-type
Read syntax diagramSkip visual syntax diagramCHARACTERCHAR(1)( integer)CHARACTERCHARVARYINGVARCHAR( integer)CHARACTERCHARLARGE OBJECTCLOB(1M)( integerKMG)BINARY VARYINGVARBINARY(integer)BINARY LARGE OBJECTBLOB(1M)( integerKMG)

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

キー式
JSON キーの名前。 名前は NULL であってはなりません (SQLSTATE 22004)。 key-expression の結果は、以下のデータ・タイプを除く、組み込み文字ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
JSON 式
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}