Movatterモバイル変換

JSON_ARRAY_APPEND(json_doc,path,val[,path,val] ...)

JSON ドキュメント内の指定された配列の末尾に値を追加し、結果を返します。 引数のいずれかがNULL である場合は、NULL を返します。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または** ワイルドカードが含まれている場合、エラーが発生します。

パスと値のペアは左から右に評価されます。 あるペアを評価して生成されたドキュメントは、次のペアが評価される新しい値になります。

パスがスカラー値またはオブジェクト値を選択すると、その値は配列内で自動ラップされ、新しい値がその配列に追加されます。 パスが JSON ドキュメント内の値を識別しないペアは無視されます。

mysql> SET @j = '["a", ["b", "c"], "d"]';mysql> SELECT JSON_ARRAY_APPEND(@j, '$[1]', 1);+----------------------------------+| JSON_ARRAY_APPEND(@j, '$[1]', 1) |+----------------------------------+| ["a", ["b", "c", 1], "d"]        |+----------------------------------+mysql> SELECT JSON_ARRAY_APPEND(@j, '$[0]', 2);+----------------------------------+| JSON_ARRAY_APPEND(@j, '$[0]', 2) |+----------------------------------+| [["a", 2], ["b", "c"], "d"]      |+----------------------------------+mysql> SELECT JSON_ARRAY_APPEND(@j, '$[1][0]', 3);+-------------------------------------+| JSON_ARRAY_APPEND(@j, '$[1][0]', 3) |+-------------------------------------+| ["a", [["b", 3], "c"], "d"]         |+-------------------------------------+mysql> SET @j = '{"a": 1, "b": [2, 3], "c": 4}';mysql> SELECT JSON_ARRAY_APPEND(@j, '$.b', 'x');+------------------------------------+| JSON_ARRAY_APPEND(@j, '$.b', 'x')  |+------------------------------------+| {"a": 1, "b": [2, 3, "x"], "c": 4} |+------------------------------------+mysql> SELECT JSON_ARRAY_APPEND(@j, '$.c', 'y');+--------------------------------------+| JSON_ARRAY_APPEND(@j, '$.c', 'y')    |+--------------------------------------+| {"a": 1, "b": [2, 3], "c": [4, "y"]} |+--------------------------------------+mysql> SET @j = '{"a": 1}';mysql> SELECT JSON_ARRAY_APPEND(@j, '$', 'z');+---------------------------------+| JSON_ARRAY_APPEND(@j, '$', 'z') |+---------------------------------+| [{"a": 1}, "z"]                 |+---------------------------------+

MySQL 5.7 では、この関数はJSON_APPEND() という名前でした。 この名前は、MySQL 8.0 ではサポートされなくなりました。

JSON_ARRAY_INSERT(json_doc,path,val[,path,val] ...)

JSON ドキュメントを更新し、ドキュメント内の配列に挿入して、変更されたドキュメントを返します。 引数のいずれかがNULL である場合は、NULL を返します。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または** ワイルドカードを含んでいるか、配列要素識別子で終わらない場合、エラーが発生します。

パスと値のペアは左から右に評価されます。 あるペアを評価して生成されたドキュメントは、次のペアが評価される新しい値になります。

パスが JSON ドキュメント内の配列を識別しないペアは無視されます。 パスが配列要素を識別する場合、対応する値がその要素の位置に挿入され、後続の値は右にシフトされます。 パスが配列の末尾より後の配列位置を識別した場合、配列の末尾に値が挿入されます。

mysql> SET @j = '["a", {"b": [1, 2]}, [3, 4]]';mysql> SELECT JSON_ARRAY_INSERT(@j, '$[1]', 'x');+------------------------------------+| JSON_ARRAY_INSERT(@j, '$[1]', 'x') |+------------------------------------+| ["a", "x", {"b": [1, 2]}, [3, 4]]  |+------------------------------------+mysql> SELECT JSON_ARRAY_INSERT(@j, '$[100]', 'x');+--------------------------------------+| JSON_ARRAY_INSERT(@j, '$[100]', 'x') |+--------------------------------------+| ["a", {"b": [1, 2]}, [3, 4], "x"]    |+--------------------------------------+mysql> SELECT JSON_ARRAY_INSERT(@j, '$[1].b[0]', 'x');+-----------------------------------------+| JSON_ARRAY_INSERT(@j, '$[1].b[0]', 'x') |+-----------------------------------------+| ["a", {"b": ["x", 1, 2]}, [3, 4]]       |+-----------------------------------------+mysql> SELECT JSON_ARRAY_INSERT(@j, '$[2][1]', 'y');+---------------------------------------+| JSON_ARRAY_INSERT(@j, '$[2][1]', 'y') |+---------------------------------------+| ["a", {"b": [1, 2]}, [3, "y", 4]]     |+---------------------------------------+mysql> SELECT JSON_ARRAY_INSERT(@j, '$[0]', 'x', '$[2][1]', 'y');+----------------------------------------------------+| JSON_ARRAY_INSERT(@j, '$[0]', 'x', '$[2][1]', 'y') |+----------------------------------------------------+| ["x", "a", {"b": [1, 2]}, [3, 4]]                  |+----------------------------------------------------+

以前の変更は配列内の次の要素の位置に影響するため、同じJSON_ARRAY_INSERT() コール内の後続のパスでこれを考慮する必要があります。 最後の例では、最初の挿入後にパスが何にも一致しなくなったため、2 番目のパスは何も挿入しません。

JSON_INSERT(json_doc,path,val[,path,val] ...)

JSON ドキュメントにデータを挿入し、結果を返します。 引数のいずれかがNULL である場合は、NULL を返します。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または** ワイルドカードが含まれている場合、エラーが発生します。

パスと値のペアは左から右に評価されます。 あるペアを評価して生成されたドキュメントは、次のペアが評価される新しい値になります。

ドキュメント内の既存のパスのパスと値のペアは無視され、既存のドキュメント値は上書きされません。 パスが次のいずれかのタイプの値を識別する場合、ドキュメント内の存在しないパスのパスと値のペアによって、ドキュメントに値が追加されます:

それ以外の場合、ドキュメント内に存在しないパスのパスと値のペアは無視され、効果はありません。

JSON_INSERT()、JSON_REPLACE() およびJSON_SET() の比較は、JSON_SET() の説明を参照してください。

mysql> SET @j = '{ "a": 1, "b": [2, 3]}';mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]');+----------------------------------------------------+| JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]') |+----------------------------------------------------+| {"a": 1, "b": [2, 3], "c": "[true, false]"}        |+----------------------------------------------------+

結果にリストされている 3 番目と最後の値は引用符で囲まれた文字列であり、2 番目の値 (出力で引用符で囲まれていない) のような配列ではありません。JSON 型への値のキャストは実行されません。 配列を配列として挿入するには、次に示すように、このようなキャストを明示的に実行する必要があります:

mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', CAST('[true, false]' AS JSON));+------------------------------------------------------------------+| JSON_INSERT(@j, '$.a', 10, '$.c', CAST('[true, false]' AS JSON)) |+------------------------------------------------------------------+| {"a": 1, "b": [2, 3], "c": [true, false]}                        |+------------------------------------------------------------------+1 row in set (0.00 sec)

JSON_MERGE(json_doc,json_doc[,json_doc] ...)

複数の JSON ドキュメントをマージします。JSON_MERGE_PRESERVE() のシノニムです。MySQL 8.0.3 では非推奨であり、将来のリリースで削除される可能性があります。

mysql> SELECT JSON_MERGE('[1, 2]', '[true, false]');+---------------------------------------+| JSON_MERGE('[1, 2]', '[true, false]') |+---------------------------------------+| [1, 2, true, false]                   |+---------------------------------------+1 row in set, 1 warning (0.00 sec)mysql> SHOW WARNINGS\G*************************** 1. row ***************************  Level: Warning   Code: 1287Message: 'JSON_MERGE' is deprecated and will be removed in a future release. \ Please use JSON_MERGE_PRESERVE/JSON_MERGE_PATCH instead1 row in set (0.00 sec)

その他の例については、JSON_MERGE_PRESERVE() のエントリを参照してください。

JSON_MERGE_PATCH(json_doc,json_doc[,json_doc] ...)

複数の JSON ドキュメントのRFC 7396 準拠マージを実行し、重複するキーを持つメンバーを保持せずにマージ結果を返します。 この関数に引数として渡されたドキュメントのいずれかが無効な場合は、エラーが発生します。

JSON_MERGE_PATCH() は、次のようにマージを実行します:

追加情報についてはJSON 値の正規化、マージおよび自動ラップを参照してください。

mysql> SELECT JSON_MERGE_PATCH('[1, 2]', '[true, false]');+---------------------------------------------+| JSON_MERGE_PATCH('[1, 2]', '[true, false]') |+---------------------------------------------+| [true, false]                               |+---------------------------------------------+mysql> SELECT JSON_MERGE_PATCH('{"name": "x"}', '{"id": 47}');+-------------------------------------------------+| JSON_MERGE_PATCH('{"name": "x"}', '{"id": 47}') |+-------------------------------------------------+| {"id": 47, "name": "x"}                         |+-------------------------------------------------+mysql> SELECT JSON_MERGE_PATCH('1', 'true');+-------------------------------+| JSON_MERGE_PATCH('1', 'true') |+-------------------------------+| true                          |+-------------------------------+mysql> SELECT JSON_MERGE_PATCH('[1, 2]', '{"id": 47}');+------------------------------------------+| JSON_MERGE_PATCH('[1, 2]', '{"id": 47}') |+------------------------------------------+| {"id": 47}                               |+------------------------------------------+mysql> SELECT JSON_MERGE_PATCH('{ "a": 1, "b":2 }',     >     '{ "a": 3, "c":4 }');+-----------------------------------------------------------+| JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }') |+-----------------------------------------------------------+| {"a": 3, "b": 2, "c": 4}                                  |+-----------------------------------------------------------+mysql> SELECT JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }',     >     '{ "a": 5, "d":6 }');+-------------------------------------------------------------------------------+| JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }','{ "a": 5, "d":6 }') |+-------------------------------------------------------------------------------+| {"a": 5, "b": 2, "c": 4, "d": 6}                                              |+-------------------------------------------------------------------------------+

この関数を使用してメンバーを削除するには、次に示すように、seond 引数で同じメンバーの値としてnull を指定します:

mysql> SELECT JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}');+--------------------------------------------------+| JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}') |+--------------------------------------------------+| {"a": 1}                                         |+--------------------------------------------------+

この例は、関数が再帰的に動作することを示しています。つまり、メンバーの値はスカラーに制限されず、JSON ドキュメントにすることもできます:

mysql> SELECT JSON_MERGE_PATCH('{"a":{"x":1}}', '{"a":{"y":2}}');+----------------------------------------------------+| JSON_MERGE_PATCH('{"a":{"x":1}}', '{"a":{"y":2}}') |+----------------------------------------------------+| {"a": {"x": 1, "y": 2}}                            |+----------------------------------------------------+

JSON_MERGE_PATCH() は、MySQL 8.0.3 以降でサポートされます。

JSON_MERGE_PATCH() と JSON_MERGE_PRESERVE() の比較. JSON_MERGE_PATCH() の動作はJSON_MERGE_PRESERVE() の動作と同じですが、次の 2 つの例外があります:

この例では、同じ 3 つの JSON オブジェクトをマージした結果を比較します。それぞれに一致するキー"a"があり、次の 2 つの関数があります:

mysql> SET @x = '{ "a": 1, "b": 2 }',     >     @y = '{ "a": 3, "c": 4 }',     >     @z = '{ "a": 5, "d": 6 }';mysql> SELECT  JSON_MERGE_PATCH(@x, @y, @z)    AS Patch,    ->         JSON_MERGE_PRESERVE(@x, @y, @z) AS Preserve\G*************************** 1. row ***************************   Patch: {"a": 5, "b": 2, "c": 4, "d": 6}Preserve: {"a": [1, 3, 5], "b": 2, "c": 4, "d": 6}

JSON_MERGE_PRESERVE(json_doc,json_doc[,json_doc] ...)

複数の JSON ドキュメントをマージし、マージ結果を返します。 引数のいずれかがNULL である場合は、NULL を返します。 引数が有効な JSON ドキュメントでない場合は、エラーが発生します。

マージは、次のルールに従って行われます。 追加情報についてはJSON 値の正規化、マージおよび自動ラップを参照してください。

mysql> SELECT JSON_MERGE_PRESERVE('[1, 2]', '[true, false]');+------------------------------------------------+| JSON_MERGE_PRESERVE('[1, 2]', '[true, false]') |+------------------------------------------------+| [1, 2, true, false]                            |+------------------------------------------------+mysql> SELECT JSON_MERGE_PRESERVE('{"name": "x"}', '{"id": 47}');+----------------------------------------------------+| JSON_MERGE_PRESERVE('{"name": "x"}', '{"id": 47}') |+----------------------------------------------------+| {"id": 47, "name": "x"}                            |+----------------------------------------------------+mysql> SELECT JSON_MERGE_PRESERVE('1', 'true');+----------------------------------+| JSON_MERGE_PRESERVE('1', 'true') |+----------------------------------+| [1, true]                        |+----------------------------------+mysql> SELECT JSON_MERGE_PRESERVE('[1, 2]', '{"id": 47}');+---------------------------------------------+| JSON_MERGE_PRESERVE('[1, 2]', '{"id": 47}') |+---------------------------------------------+| [1, 2, {"id": 47}]                          |+---------------------------------------------+mysql> SELECT JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }',     >    '{ "a": 3, "c": 4 }');+--------------------------------------------------------------+| JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c":4 }') |+--------------------------------------------------------------+| {"a": [1, 3], "b": 2, "c": 4}                                |+--------------------------------------------------------------+mysql> SELECT JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c": 4 }',     >    '{ "a": 5, "d": 6 }');+----------------------------------------------------------------------------------+| JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c": 4 }','{ "a": 5, "d": 6 }') |+----------------------------------------------------------------------------------+| {"a": [1, 3, 5], "b": 2, "c": 4, "d": 6}                                         |+----------------------------------------------------------------------------------+

この関数は、JSON_MERGE() のシノニムとして MySQL 8.0.3 に追加されました。JSON_MERGE() 関数は非推奨になり、MySQL の将来のリリースで削除される予定です。

この関数は、JSON_MERGE_PATCH() と似ていますが、重要な点で異なります。詳細は、JSON_MERGE_PATCH() と JSON_MERGE_PRESERVE() の比較 を参照してください。

JSON_REMOVE(json_doc,path[,path] ...)

JSON ドキュメントからデータを削除し、結果を返します。 引数のいずれかがNULL である場合は、NULL を返します。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、$ であるか、* または** ワイルドカードが含まれている場合、エラーが発生します。

path 引数は左から右に評価されます。 あるパスを評価して生成されたドキュメントは、次のパスが評価される新しい値になります。

削除する要素がドキュメントに存在しない場合、エラーにはなりません。その場合、パスはドキュメントに影響しません。

mysql> SET @j = '["a", ["b", "c"], "d"]';mysql> SELECT JSON_REMOVE(@j, '$[1]');+-------------------------+| JSON_REMOVE(@j, '$[1]') |+-------------------------+| ["a", "d"]              |+-------------------------+

JSON_REPLACE(json_doc,path,val[,path,val] ...)

JSON ドキュメント内の既存の値を置換し、結果を返します。 引数のいずれかがNULL である場合は、NULL を返します。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または** ワイルドカードが含まれている場合、エラーが発生します。

パスと値のペアは左から右に評価されます。 あるペアを評価して生成されたドキュメントは、次のペアが評価される新しい値になります。

ドキュメント内の既存のパスのパスと値のペアによって、既存のドキュメント値が新しい値で上書きされます。 ドキュメント内に存在しないパスのパスと値のペアは無視され、効果はありません。

MySQL 8.0.4 では、オプティマイザは、古いドキュメントを削除して新しいドキュメント全体をカラムに書き込むかわりに、JSON カラムの部分的なインプレース更新を実行できます。 この最適化は、JSON_REPLACE() 関数を使用し、JSON 値の部分更新 で説明されている条件を満たす UPDATE ステートメントに対して実行できます。

JSON_INSERT()、JSON_REPLACE() およびJSON_SET() の比較は、JSON_SET() の説明を参照してください。

mysql> SET @j = '{ "a": 1, "b": [2, 3]}';mysql> SELECT JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]');+-----------------------------------------------------+| JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]') |+-----------------------------------------------------+| {"a": 10, "b": [2, 3]}                              |+-----------------------------------------------------+

JSON_SET(json_doc,path,val[,path,val] ...)

JSON ドキュメントのデータを挿入または更新し、結果を返します。 いずれかの引数がNULL またはpath の場合、NULL を戻します (指定されている場合)。json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または** ワイルドカードが含まれている場合、エラーが発生します。

パスと値のペアは左から右に評価されます。 あるペアを評価して生成されたドキュメントは、次のペアが評価される新しい値になります。

ドキュメント内の既存のパスのパスと値のペアによって、既存のドキュメント値が新しい値で上書きされます。 パスが次のいずれかのタイプの値を識別する場合、ドキュメント内の存在しないパスのパスと値のペアによって、ドキュメントに値が追加されます:

それ以外の場合、ドキュメント内に存在しないパスのパスと値のペアは無視され、効果はありません。

MySQL 8.0.4 では、オプティマイザは、古いドキュメントを削除して新しいドキュメント全体をカラムに書き込むかわりに、JSON カラムの部分的なインプレース更新を実行できます。 この最適化は、JSON_SET() 関数を使用し、JSON 値の部分更新 で説明されている条件を満たす UPDATE ステートメントに対して実行できます。

JSON_SET()、JSON_INSERT() およびJSON_REPLACE() 関数が関連しています:

次の例では、ドキュメント ($.a) に存在するパスと存在しないパス ($.c) を使用して、これらの違いを示します:

mysql> SET @j = '{ "a": 1, "b": [2, 3]}';mysql> SELECT JSON_SET(@j, '$.a', 10, '$.c', '[true, false]');+-------------------------------------------------+| JSON_SET(@j, '$.a', 10, '$.c', '[true, false]') |+-------------------------------------------------+| {"a": 10, "b": [2, 3], "c": "[true, false]"}    |+-------------------------------------------------+mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]');+----------------------------------------------------+| JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]') |+----------------------------------------------------+| {"a": 1, "b": [2, 3], "c": "[true, false]"}        |+----------------------------------------------------+mysql> SELECT JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]');+-----------------------------------------------------+| JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]') |+-----------------------------------------------------+| {"a": 10, "b": [2, 3]}                              |+-----------------------------------------------------+

JSON_UNQUOTE(json_val)

JSON 値を引用符で囲まずに、結果をutf8mb4 文字列として返します。 引数がNULL の場合、NULL を返します。 値の先頭と末尾が二重引用符であるが、有効な JSON 文字列リテラルではない場合、エラーが発生します。

NO_BACKSLASH_ESCAPES SQL モードが有効になっている場合を除いて、一部のシーケンスが文字列内で特別な意味を持ちます。 これらのシーケンスはいずれも、エスケープ文字として知られるバックスラッシュ (\) で始まります。 MySQL は、表12.23「JSON_UNQUOTE() 特殊文字エスケープシーケンス」に示すエスケープシーケンスを認識します。 ほかのすべてのエスケープシーケンスでは、バックスラッシュは無視されます。 つまり、エスケープされた文字がエスケープされていないと解釈されます。 たとえば、\x は単なるx です。 これらの順序では、大/小文字が区別されます。 たとえば、\b はバックスペースとして解釈されますが、\B はB として解釈されます。

この関数の 2 つの簡単な使用例を次に示します:

mysql> SET @j = '"abc"';mysql> SELECT @j, JSON_UNQUOTE(@j);+-------+------------------+| @j    | JSON_UNQUOTE(@j) |+-------+------------------+| "abc" | abc              |+-------+------------------+mysql> SET @j = '[1, 2, 3]';mysql> SELECT @j, JSON_UNQUOTE(@j);+-----------+------------------+| @j        | JSON_UNQUOTE(@j) |+-----------+------------------+| [1, 2, 3] | [1, 2, 3]        |+-----------+------------------+

次の一連の例は、NO_BACKSLASH_ESCAPES を無効にして有効にした場合にJSON_UNQUOTE がエスケープを処理する方法を示しています:

mysql> SELECT @@sql_mode;+------------+| @@sql_mode |+------------+|            |+------------+mysql> SELECT JSON_UNQUOTE('"\\t\\u0032"');+------------------------------+| JSON_UNQUOTE('"\\t\\u0032"') |+------------------------------+|       2                           |+------------------------------+mysql> SET @@sql_mode = 'NO_BACKSLASH_ESCAPES';mysql> SELECT JSON_UNQUOTE('"\\t\\u0032"');+------------------------------+| JSON_UNQUOTE('"\\t\\u0032"') |+------------------------------+| \t\u0032                     |+------------------------------+mysql> SELECT JSON_UNQUOTE('"\t\u0032"');+----------------------------+| JSON_UNQUOTE('"\t\u0032"') |+----------------------------+|       2                         |+----------------------------+