JSON_ARRAY_APPEND

説明

この関数は、指定された値をJSONドキュメント内の指定された配列の末尾に追加して結果を返します。これは、関数 JSON_APPEND() のエイリアスです。

構文

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

説明

json_doc パラメータはJSONドキュメントを指定し、path はパスパラメータです。いずれかのパラメータが NULL の場合、NULL を返します。

次の場合にエラーが発生します：

• json_doc パラメータが有効なJSONドキュメントではありません。

• path パラメータが有効なパス式ではありません。

• path パラメータに * または ** ワイルドカードが含まれています。

パス値ペア(path-value pair)は、左から右への順序で評価されます。評価されたパス値ペア(path-value pair)によって生成されたドキュメントは、次のペアを評価するための新しい値となります。

パスに対応する値がスカラーまたはオブジェクト値の場合、その値は自動的に配列にラップされ、新しい値がその配列に追加されます。JSONドキュメント内でパスによって識別されない配列に属するパス値ペア(path-value pair)は無視されます。

例

• 以下の例では、ユーザー変数@jnを定義し、JSON文字列を含みます。このJSON文字列は、JSON配列を表します。

  obclient> SET @jn = '["a", ["b", "c"], "d","e"]';
  

  変数@jnのパスが$[1]の配列の末尾に値1を追加します。

  obclient> SELECT JSON_ARRAY_APPEND(@jn, '$[1]', 1);
  

  ここで、$[1]はJSON配列の2番目の要素に対応します。実行結果は次のとおりです：

  +-----------------------------------+
  | JSON_ARRAY_APPEND(@jn, '$[1]', 1) |
  +-----------------------------------+
  | ["a", ["b", "c", 1], "d", "e"]    |
  +-----------------------------------+
  1 row in set
  

  変数@jnのパスが$[0]の配列の末尾に値2を追加します。

  obclient> SELECT JSON_ARRAY_APPEND(@jn, '$[0]', 2);
  

  ここで、$[0]はJSON配列の最初の要素に対応します。実行結果は次のとおりです：

  +-----------------------------------+
  | JSON_ARRAY_APPEND(@jn, '$[0]', 2) |
  +-----------------------------------+
  | [["a", 2], ["b", "c"], "d", "e"]  |
  +-----------------------------------+
  1 row in set
  

  ["b", "c"]は配列であるため、変数@jnのパスが$[1][0]の配列の末尾に値3を追加できます。

  obclient> SELECT JSON_ARRAY_APPEND(@jn, '$[1][0]', 3);
  

  実行結果は次のとおりです：

  +--------------------------------------+
  | JSON_ARRAY_APPEND(@jn, '$[1][0]', 3) |
  +--------------------------------------+
  | ["a", [["b", 3], "c"], "d", "e"]     |
  +--------------------------------------+
  1 row in set
  

• 以下の例では、ユーザー変数@jempを定義し、JSON文字列を含みます。このJSON文字列はオブジェクトを表します。このオブジェクトには3つのキーと値のペアが含まれています："a"の値は数値1です；"b"の値は数値2と3を含む配列です；"c"の値は数値4です。

  obclient> SET @jemp = '{"a": 1, "b": [2, 3], "c": 4}';
  

  文字列xを変数@jempのパスが$.bの配列の末尾に追加します。

  obclient> SELECT JSON_ARRAY_APPEND(@jemp, '$.b', 'x');
  

  ここで、$.bは"b"キーに対応する配列を表します。実行結果は次のとおりです：

  +--------------------------------------+
  | JSON_ARRAY_APPEND(@jemp, '$.b', 'x') |
  +--------------------------------------+
  | {"a": 1, "b": [2, 3, "x"], "c": 4}   |
  +--------------------------------------+
  1 row in set
  

  同様に、文字列yを変数@jempのパスが$.cの配列の末尾に追加します。

  obclient> SELECT JSON_ARRAY_APPEND(@jemp, '$.c', 'y');
  

  ここで、$.cは"c"キーに対応する配列を表します。実行結果は次のとおりです：

  +--------------------------------------+
  | JSON_ARRAY_APPEND(@jemp, '$.c', 'y') |
  +--------------------------------------+
  | {"a": 1, "b": [2, 3], "c": [4, "y"]} |
  +--------------------------------------+
  1 row in set
  

• 以下の例では、ユーザー変数@tempを定義し、単純なJSONオブジェクトを含みます。このオブジェクトでは、キーは"a"で、値は数値5です。

  obclient> SET @temp = '{"a": 5}';
  

  文字列zを変数@tempのパスが$の配列の末尾に追加します。

  obclient> SELECT JSON_ARRAY_APPEND(@temp, '$', 'z');
  

  注意すべき点として、パス$と指定されていることから、これはJSONドキュメントのルートレベル、つまり全体のJSONオブジェクトを表し、JSONオブジェクトにキーと値のペアを追加するわけではありません。実行結果は次のとおりです：

  +------------------------------------+
  | JSON_ARRAY_APPEND(@temp, '$', 'z') |
  +------------------------------------+
  | [{"a": 5}, "z"]                    |
  +------------------------------------+
  1 row in set
  

関連ドキュメント

JSON_APPEND