カテゴリ:

変換関数半構造化データ関数 (キャスト)

TO_JSON

VARIANT 値を値の JSON 表現を含む文字列に変換します。入力が NULL の場合は、結果も NULL です。

構文

TO_JSON( <expr> )

引数

有効な JSON 情報を保持する VARIANT 型の式です。

戻り値

戻り値は VARCHAR 型です。

使用上の注意

  • 入力が NULL の場合は、出力も NULL です。入力が JSON null を含む VARIANT である場合、戻り値は文字列 '"null"' (つまり、二重引用符で囲まれた"null"という単語)です。例は、下記の例セクションに含まれています。

  • JSON オブジェクト(別名「ディクショナリ」または「ハッシュ」)は、キーと値のペアの 順序付けられていない セットです。 TO_JSON が文字列を生成する場合、その文字列内のキーと値のペアの順序は予測できません。

  • TO_JSON および PARSE_JSON は(ほぼ)逆または相反する関数です。

    • PARSE_JSON 関数は入力として文字列を取り、 JSON互換のバリアントを返します。

    • TO_JSON 関数は JSON互換バリアントを受け取り、文字列を返します。

    Xが有効な JSON を含む文字列である場合、次は(概念的に)trueです。

    X = TO_JSON(PARSE_JSON(X));

    例えば、次は(概念的に)trueです。

    '{"pi":3.14,"e":2.71}' = TO_JSON(PARSE_JSON('{"pi":3.14,"e":2.71}'))

    ただし、関数は次の2つの理由で完全には逆数ではありません。

    • TO_JSON によって生成される文字列内のキーと値のペアの順序は予測できません。

    • TO_JSON によって生成された文字列には、 PARSE_JSON に渡される文字列よりも少ない空白を含めることができます。

    次は同等の JSONですが、同等の文字列ではありません。

    • {"pi": 3.14, "e": 2.71}

    • {"e":2.71,"pi":3.14}

これは TO_JSONPARSE_JSON の短い例です。

CREATE TABLE jdemo1 (v VARIANT);
INSERT INTO jdemo1 SELECT PARSE_JSON('{"food":"bard"}');
SELECT v, v:food, TO_JSON(v) FROM jdemo1;
+------------------+--------+-----------------+
| V                | V:FOOD | TO_JSON(V)      |
|------------------+--------+-----------------|
| {                | "bard" | {"food":"bard"} |
|   "food": "bard" |        |                 |
| }                |        |                 |
+------------------+--------+-----------------+

次の例は、 PARSE_JSONTO_JSON の NULL の処理を示しています。

SELECT TO_JSON(NULL), TO_JSON('null'::VARIANT),
       PARSE_JSON(NULL), PARSE_JSON('null');
+---------------+--------------------------+------------------+--------------------+
| TO_JSON(NULL) | TO_JSON('NULL'::VARIANT) | PARSE_JSON(NULL) | PARSE_JSON('NULL') |
|---------------+--------------------------+------------------+--------------------|
| NULL          | "null"                   | NULL             | null               |
+---------------+--------------------------+------------------+--------------------+

次の例は、 PARSE_JSONTO_JSONTO_VARIANT の間の関係を示しています。

テーブルを作成し、 VARCHAR、汎用 VARIANT、 JSON 互換の VARIANT データを追加します。INSERT ステートメントは VARCHAR 値を挿入し、 UPDATE ステートメントはその VARCHAR に対応する JSON 値を生成します。

CREATE or replace TABLE jdemo2 (varchar1 VARCHAR, variant1 VARIANT,
    variant2 VARIANT);
INSERT INTO jdemo2 (varchar1) VALUES ('{"PI":3.14}');
UPDATE jdemo2 SET variant1 = PARSE_JSON(varchar1);

このクエリは、 TO_JSONPARSE_JSON が概念的に逆関数であることを示しています。

SELECT varchar1, PARSE_JSON(varchar1), variant1,  TO_JSON(variant1),
                 PARSE_JSON(varchar1) = variant1, TO_JSON(variant1) = varchar1
    FROM jdemo2;
+-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------+
| VARCHAR1    | PARSE_JSON(VARCHAR1) | VARIANT1     | TO_JSON(VARIANT1) | PARSE_JSON(VARCHAR1) = VARIANT1 | TO_JSON(VARIANT1) = VARCHAR1 |
|-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------|
| {"PI":3.14} | {                    | {            | {"PI":3.14}       | True                            | True                         |
|             |   "PI": 3.14         |   "PI": 3.14 |                   |                                 |                              |
|             | }                    | }            |                   |                                 |                              |
+-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------+

ただし、関数は厳密には逆数ではありません。空白またはキーと値のペアの順序が違うときは、出力が入力と一致しない場合があります。例:

SELECT
    TO_JSON(PARSE_JSON('{"b":1,"a":2}')),
    TO_JSON(PARSE_JSON('{"b":1,"a":2}')) = '{"b":1,"a":2}',
    TO_JSON(PARSE_JSON('{"b":1,"a":2}')) = '{"a":2,"b":1}'
    ;
+--------------------------------------+--------------------------------------------------------+--------------------------------------------------------+
| TO_JSON(PARSE_JSON('{"B":1,"A":2}')) | TO_JSON(PARSE_JSON('{"B":1,"A":2}')) = '{"B":1,"A":2}' | TO_JSON(PARSE_JSON('{"B":1,"A":2}')) = '{"A":2,"B":1}' |
|--------------------------------------+--------------------------------------------------------+--------------------------------------------------------|
| {"a":2,"b":1}                        | False                                                  | True                                                   |
+--------------------------------------+--------------------------------------------------------+--------------------------------------------------------+

PARSE_JSONTO_VARIANT はどちらも文字列を取り、バリアントを返すことができますが、同等ではありません。次のコードは、 PARSE_JSON を使用して1つの列を更新し、 TO_VARIANT を使用して他の列を更新します。(列 variant1 の更新は、同じ関数呼び出しを使用して以前に更新されたため不要です。ただし、列を更新するために呼び出される関数を並べて確認できるように、以下のコードで再度更新します)。

UPDATE jdemo2 SET
    variant1 = PARSE_JSON(varchar1),
    variant2 = TO_VARIANT(varchar1);

以下のクエリは、 PARSE_JSON の出力と TO_VARIANT の出力が同じでないことを示しています。空白の些細な違いに加えて、引用符には大きな違いがあります。

SELECT variant1, variant2, variant1 = variant2 FROM jdemo2;
+--------------+-----------------+---------------------+
| VARIANT1     | VARIANT2        | VARIANT1 = VARIANT2 |
|--------------+-----------------+---------------------|
| {            | "{\"PI\":3.14}" | False               |
|   "PI": 3.14 |                 |                     |
| }            |                 |                     |
+--------------+-----------------+---------------------+