The functions in this section modify JSON values and return the result.本节中的函数修改JSON值并返回结果。
JSON_ARRAY_APPEND(
json_doc
, path
, val
[, path
, val
] ...)
Appends values to the end of the indicated arrays within a JSON document and returns the result. 将值附加到JSON文档中指定数组的末尾并返回结果。Returns 如果任一个参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or contains a *
or **
wildcard.json_doc
参数不是有效的JSON文档,或者任何path
参数都不是有效的路径表达式,或者包含*
或**
通配符,则会发生错误。
The path-value pairs are evaluated left to right. 路径值对从左到右求值。The document produced by evaluating one pair becomes the new value against which the next pair is evaluated.通过对一对进行求值而生成的文档将成为下一对的求值所依据的新值。
If a path selects a scalar or object value, that value is autowrapped within an array and the new value is added to that array. 如果路径选择标量值或对象值,则该值将自动包装到数组中,并将新值添加到该数组中。Pairs for which the path does not identify any value in the JSON document are ignored.路径未标识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"] | +---------------------------------+
In MySQL 5.7, this function was named 在MySQL5.7中,这个函数名为JSON_APPEND()
. JSON_APPEND()
。That name is no longer supported in MySQL 8.0.MySQL 8.0不再支持该名称。
JSON_ARRAY_INSERT(
json_doc
, path
, val
[, path
, val
] ...)
Updates a JSON document, inserting into an array within the document and returning the modified document. 更新JSON文档,将其插入到文档中的数组中并返回修改后的文档。Returns 如果任何参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or contains a *
or **
wildcard or does not end with an array element identifier.json_doc
参数不是有效的json文档,或者任何path
参数都不是有效的路径表达式,或者包含*
或**
通配符,或者没有以数组元素标识符结尾,则会发生错误。
The path-value pairs are evaluated left to right. 路径值对从左到右求值。The document produced by evaluating one pair becomes the new value against which the next pair is evaluated.通过对一对进行求值而生成的文档将成为下一对的求值所依据的新值。
Pairs for which the path does not identify any array in the JSON document are ignored. 路径未标识JSON文档中任何数组的对将被忽略。If a path identifies an array element, the corresponding value is inserted at that element position, shifting any following values to the right. 如果路径标识一个数组元素,则在该元素位置插入相应的值,并向右移动以下任何值。If a path identifies an array position past the end of an array, the value is inserted at the end of the array.如果路径标识超过数组结尾的数组位置,则该值将插入数组结尾。
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]] | +----------------------------------------------------+
Earlier modifications affect the positions of the following elements in the array, so subsequent paths in the same 前面的修改会影响以下元素在数组中的位置,因此在同一个JSON_ARRAY_INSERT()
call should take this into account. JSON_array_INSERT()
调用中的后续路径应该考虑到这一点。In the final example, the second path inserts nothing because the path no longer matches anything after the first insert.在最后一个示例中,第二条路径不插入任何内容,因为该路径在第一次插入之后不再匹配任何内容。
JSON_INSERT(
json_doc
, path
, val
[, path
, val
] ...)
Inserts data into a JSON document and returns the result. 将数据插入JSON文档并返回结果。Returns 如果任何参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or contains a *
or **
wildcard.json_doc
参数不是有效的JSON文档,或者任何path
参数都不是有效的路径表达式,或者包含*
或**
通配符,则会发生错误。
The path-value pairs are evaluated left to right. 路径值对从左到右求值。The document produced by evaluating one pair becomes the new value against which the next pair is evaluated.通过对一对进行求值而生成的文档将成为下一对的求值所依据的新值。
A path-value pair for an existing path in the document is ignored and does not overwrite the existing document value. 文档中现有路径的路径值对将被忽略,并且不会覆盖现有文档值。A path-value pair for a nonexisting path in the document adds the value to the document if the path identifies one of these types of values:文档中不存在的路径的路径-值对将值添加到文档中,前提是该路径标识以下类型的值之一:
A member not present in an existing object. 现有对象中不存在的成员。The member is added to the object and associated with the new value.成员被添加到对象并与新值关联。
A position past the end of an existing array. 超过现有数组末尾的位置。The array is extended with the new value. 数组将用新值扩展。If the existing value is not an array, it is autowrapped as an array, then extended with the new value.如果现有值不是数组,则将其自动包装为数组,然后使用新值进行扩展。
Otherwise, a path-value pair for a nonexisting path in the document is ignored and has no effect.否则,文档中不存在的路径的路径-值对将被忽略,并且无效。
For a comparison of 有关JSON_INSERT()
, JSON_REPLACE()
, and JSON_SET()
, see the discussion of JSON_SET()
.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]"} | +----------------------------------------------------+
The third and final value listed in the result is a quoted string and not an array like the second one (which is not quoted in the output); no casting of values to the JSON type is performed. 结果中列出的第三个也是最后一个值是带引号的字符串,而不是像第二个那样的数组(在输出中不带引号);不会将值强制转换为JSON类型。To insert the array as an array, you must perform such casts explicitly, as shown here:要将数组作为数组插入,必须显式执行此类强制转换,如下所示:
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
] ...)
Merges two or more JSON documents. 合并两个或多个JSON文档。Synonym for JSON_MERGE_PRESERVE()
; deprecated in MySQL 8.0.3 and subject to removal in a future release.JSON_MERGE_PRESERVE()
的同义词;在MySQL8.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: 1287 Message: 'JSON_MERGE' is deprecated and will be removed in a future release. \ Please use JSON_MERGE_PRESERVE/JSON_MERGE_PATCH instead 1 row in set (0.00 sec)
For additional examples, see the entry for 有关其他示例,请参见JSON_MERGE_PRESERVE()
.JSON_MERGE_PRESERVE()
的条目。
JSON_MERGE_PATCH(
json_doc
, json_doc
[, json_doc
] ...)
Performs an RFC 7396 compliant merge of two or more JSON documents and returns the merged result, without preserving members having duplicate keys. 对两个或多个JSON文档执行符合RFC 7396的合并,并返回合并结果,而不保留具有重复键的成员。Raises an error if at least one of the documents passed as arguments to this function is not valid.如果作为参数传递给此函数的文档中至少有一个无效,则引发错误。
For an explanation and example of the differences between this function and 有关此函数与JSON_MERGE_PRESERVE()
, see JSON_MERGE_PATCH() compared with JSON_MERGE_PRESERVE().JSON_MERGE_PRESERVE()
之间差异的说明和示例,请参阅JSON_MERGE_PATCH()
与JSON_MERGE_PRESERVE()
的比较。
JSON_MERGE_PATCH()
performs a merge as follows:JSON_MERGE_PATCH()
执行如下合并:
If the first argument is not an object, the result of the merge is the same as if an empty object had been merged with the second argument.如果第一个参数不是对象,则合并的结果与空对象与第二个参数合并的结果相同。
If the second argument is not an object, the result of the merge is the second argument.如果第二个参数不是对象,则合并的结果就是第二个参数。
If both arguments are objects, the result of the merge is an object with the following members:如果两个参数都是对象,则合并的结果是具有以下成员的对象:
All members of the first object which do not have a corresponding member with the same key in the second object.第一个对象的所有成员,在第二个对象中没有具有相同键的对应成员。
All members of the second object which do not have a corresponding key in the first object, and whose value is not the JSON 第二个对象的所有成员,这些成员在第一个对象中没有对应的键,并且其值不是JSON null
literal.null
文本。
All members with a key that exists in both the first and the second object, and whose value in the second object is not the JSON 所有成员的键都存在于第一个和第二个对象中,并且其在第二个对象中的值不是JSON null
literal. null
文本。The values of these members are the results of recursively merging the value in the first object with the value in the second object.这些成员的值是递归地将第一个对象中的值与第二个对象中的值合并的结果。
For additional information, see Normalization, Merging, and Autowrapping of JSON Values.有关更多信息,请参见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} | +-------------------------------------------------------------------------------+
You can use this function to remove a member by specifying 通过在第二个参数中指定null
as the value of the same member in the second argument, as shown here:null
作为同一成员的值,可以使用此函数删除成员,如下所示:
mysql> SELECT JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}');
+--------------------------------------------------+
| JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}') |
+--------------------------------------------------+
| {"a": 1} |
+--------------------------------------------------+
This example shows that the function operates in a recursive fashion; that is, values of members are not limited to scalars, but rather can themselves be JSON documents:这个例子显示函数以递归的方式运行;也就是说,成员的值不限于标量,而是可以是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()
is supported in MySQL 8.0.3 and later.JSON_MERGE_PATCH()
是在MySQL 8.0.3中新增的。
JSON_MERGE_PATCH() compared with JSON_MERGE_PRESERVE().JSON_MERGE_PATCH()
与JSON_MERGE_PRESERVE()
的比较。 The behavior of JSON_MERGE_PATCH()
is the same as that of JSON_MERGE_PRESERVE()
, with the following two exceptions:JSON_MERGE_PATCH()
的行为与JSON_MERGE_PRESERVE()
相同,但有以下两个例外:
JSON_MERGE_PATCH()
removes any member in the first object with a matching key in the second object, provided that the value associated with the key in the second object is not JSON null
.JSON_MERGE_PATCH()
删除第一个对象中与第二个对象中的键匹配的任何成员,前提是与第二个对象中的键关联的值不是JSON null
。
If the second object has a member with a key matching a member in the first object, 如果第二个对象有一个成员,其键与第一个对象中的成员匹配,则JSON_MERGE_PATCH()
replaces the value in the first object with the value in the second object, whereas JSON_MERGE_PRESERVE()
appends the second value to the first value.JSON_MERGE_PATCH()
将第一个对象中的值替换为第二个对象中的值,而JSON_MERGE_PRESERVE()
将第二个值追加到第一个值。
This example compares the results of merging the same 3 JSON objects, each having a matching key 此示例将合并相同的3个JSON对象(每个对象都有一个匹配的键"a"
, with each of these two functions:"a"
)的结果与以下两个函数进行比较:
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
] ...)
Merges two or more JSON documents and returns the merged result. 合并两个或多个JSON文档并返回合并结果。Returns 如果任何参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if any argument is not a valid JSON document.如果任何参数不是有效的JSON文档,则会发生错误。
Merging takes place according to the following rules. 合并根据以下规则进行。For additional information, see Normalization, Merging, and Autowrapping of JSON Values.有关更多信息,请参见JSON值的规范化、合并和自动包装。
Adjacent arrays are merged to a single array.相邻阵列合并为单个阵列。
Adjacent objects are merged to a single object.相邻对象合并为单个对象。
A scalar value is autowrapped as an array and merged as an array.标量值自动包装为数组并合并为数组。
An adjacent array and object are merged by autowrapping the object as an array and merging the two arrays.通过将对象自动包装为数组并合并两个数组,可以合并相邻的数组和对象。
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} | +----------------------------------------------------------------------------------+
This function was added in MySQL 8.0.3 as a synonym for 此函数是在MySQL 8.0.3中作为JSON_MERGE()
. JSON_MERGE()
的同义词添加的。The JSON_MERGE()
function is now deprecated, and is subject to removal in a future release of MySQL.JSON_MERGE()
函数现在已被弃用,在MySQL的未来版本中可能会被删除。
This function is similar to but differs from 此函数与JSON_MERGE_PATCH()
in significant respects; see JSON_MERGE_PATCH() compared with JSON_MERGE_PRESERVE(), for more information.JSON_MERGE_PATCH()
类似,但在重要方面有所不同;有关详细信息,请参阅JSON_MERGE_PATCH()
与JSON_MERGE_PRESERVE()
的比较。
JSON_REMOVE(
json_doc
, path
[, path
] ...)
Removes data from a JSON document and returns the result. 从JSON文档中删除数据并返回结果。Returns 如果任何参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or is $
or contains a *
or **
wildcard.json_doc
参数不是有效的JSON文档,或者任何path
参数都不是有效的路径表达式,或者是$
或包含*
或**
通配符,则会发生错误。
The path
arguments are evaluated left to right. path
参数从左到右求值。The document produced by evaluating one path becomes the new value against which the next path is evaluated.通过计算一条路径生成的文档将成为计算下一条路径的新值。
It is not an error if the element to be removed does not exist in the document; in that case, the path does not affect the document.如果要删除的元素在文档中不存在,则不是错误;在这种情况下,路径不会影响文档。
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
] ...)
Replaces existing values in a JSON document and returns the result. 替换JSON文档中的现有值并返回结果。Returns 如果任何参数为NULL
if any argument is NULL
. NULL
,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or contains a *
or **
wildcard.json_doc
参数不是有效的JSON文档,或者任何path
参数都不是有效的路径表达式,或者包含*
或**
通配符,则会发生错误。
The path-value pairs are evaluated left to right. 路径值对从左到右求值。The document produced by evaluating one pair becomes the new value against which the next pair is evaluated.通过对一对进行求值而生成的文档将成为下一对的求值所依据的新值。
A path-value pair for an existing path in the document overwrites the existing document value with the new value. 文档中现有路径的路径值对将用新值覆盖现有文档值。A path-value pair for a nonexisting path in the document is ignored and has no effect.文档中不存在的路径的路径-值对将被忽略且无效。
In MySQL 8.0.4, the optimizer can perform a partial, in-place update of a 在MySQL 8.0.4中,优化器可以执行JSON
column instead of removing the old document and writing the new document in its entirety to the column. JSON
列的局部就地更新,而不是删除旧文档并将新文档全部写入该列。This optimization can be performed for an update statement that uses the 可以对使用JSON_REPLACE()
function and meets the conditions outlined in Partial Updates of JSON Values.JSON_REPLACE()
函数并满足部分更新JSON值中列出的条件的更新语句执行此优化。
For a comparison of 有关JSON_INSERT()
, JSON_REPLACE()
, and JSON_SET()
, see the discussion of JSON_SET()
.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
] ...)
Inserts or updates data in a JSON document and returns the result. 在JSON文档中插入或更新数据并返回结果。Returns 如果任何参数为NULL
if any argument is NULL
or path
, if given, does not locate an object. NULL
,或path
(如果给定)未找到对象,则返回NULL
。An error occurs if the 如果json_doc
argument is not a valid JSON document or any path
argument is not a valid path expression or contains a *
or **
wildcard.json_doc
参数不是有效的JSON文档,或者任何path
参数都不是有效的路径表达式,或者包含*
或**
通配符,则会发生错误。
The path-value pairs are evaluated left to right. 路径值对从左到右求值。The document produced by evaluating one pair becomes the new value against which the next pair is evaluated.通过对一对进行求值而生成的文档将成为下一对的求值所依据的新值。
A path-value pair for an existing path in the document overwrites the existing document value with the new value. 文档中现有路径的路径值对将用新值覆盖现有文档值。A path-value pair for a nonexisting path in the document adds the value to the document if the path identifies one of these types of values:文档中不存在的路径的路径-值对将值添加到文档中,前提是该路径标识以下类型的值之一:
A member not present in an existing object. 现有对象中不存在的成员。The member is added to the object and associated with the new value.成员被添加到对象并与新值关联。
A position past the end of an existing array. 超过现有数组末尾的位置。The array is extended with the new value. 数组将用新值扩展。If the existing value is not an array, it is autowrapped as an array, then extended with the new value.如果现有值不是数组,则将其自动包装为数组,然后使用新值进行扩展。
Otherwise, a path-value pair for a nonexisting path in the document is ignored and has no effect.否则,文档中不存在的路径的路径-值对将被忽略,并且无效。
In MySQL 8.0.4, the optimizer can perform a partial, in-place update of a 在MySQL 8.0.4中,优化器可以执行JSON
column instead of removing the old document and writing the new document in its entirety to the column. JSON
列的局部就地更新,而不是删除旧文档并将新文档全部写入该列。This optimization can be performed for an update statement that uses the 可以对使用JSON_SET()
function and meets the conditions outlined in Partial Updates of JSON Values.JSON_SET()
函数并满足部分更新JSON值中列出的条件的更新语句执行此优化。
The JSON_SET()
, JSON_INSERT()
, and JSON_REPLACE()
functions are related:JSON_SET()
、JSON_INSERT()
和JSON_REPLACE()
函数是相关的:
JSON_SET()
replaces existing values and adds nonexisting values.JSON_SET()
替换现有值并添加不存在的值。
JSON_INSERT()
inserts values without replacing existing values.JSON_INSERT()
插入值而不替换现有值。
JSON_REPLACE()
replaces only existing values.JSON_REPLACE()
只替换现有值。
The following examples illustrate these differences, using one path that does exist in the document (以下示例使用文档中存在的一个路径($.a
) and another that does not exist ($.c
):$.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]} | +-----------------------------------------------------+
Unquotes JSON value and returns the result as a 未加引号的JSON值并以utf8mb4
string. utf8mb4
字符串的形式返回结果。Returns 如果参数为NULL
if the argument is NULL
. NULL
,则返回NULL
。An error occurs if the value starts and ends with double quotes but is not a valid JSON string literal.如果值以双引号开始和结束,但不是有效的JSON字符串文本,则会发生错误。
Within a string, certain sequences have special meaning unless the 在字符串中,某些序列具有特殊的含义,除非启用了NO_BACKSLASH_ESCAPES
SQL mode is enabled. NO_BACKSLASH_ESCAPES
SQL模式。Each of these sequences begins with a backslash (每个序列都以反斜杠(\
), known as the escape character. \
)开始,称为转义字符。MySQL recognizes the escape sequences shown in Table 12.23, “JSON_UNQUOTE() Special Character Escape Sequences”. MySQL识别表12.23“JSON_UNQUOTE()
特殊字符转义序列”中所示的转义序列。For all other escape sequences, backslash is ignored. 对于所有其他转义序列,将忽略反斜杠。That is, the escaped character is interpreted as if it was not escaped. 也就是说,转义字符被解释为没有转义。For example, 例如,\x
is just x
. \x
就是x
。These sequences are case-sensitive. 这些序列区分大小写。For example, 例如,\b
is interpreted as a backspace, but \B
is interpreted as B
.\b
被解释为退格,但是\B
被解释为B
。
Table 12.23 JSON_UNQUOTE() Special Character Escape SequencesJSON_UNQUOTE()
特殊字符转义序列
\" | " ) character" )字符 |
\b | |
\f | |
\n | |
\r | |
\t | |
\\ | \ ) character\ )字符 |
\u | XXXX |
Two simple examples of the use of this function are shown here:使用此函数的两个简单示例如下所示:
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] | +-----------+------------------+
The following set of examples shows how 下面的一组示例显示了JSON_UNQUOTE
handles escapes with NO_BACKSLASH_ESCAPES
disabled and enabled:JSON_UNQUOTE
如何处理转义,而不禁用和启用NO_BACKSLASH_ESCAPES
:
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 | +----------------------------+