JSON_VALUE

描述

该函数从指定路径中提取 JSON 文档中的值，并返回提取的值，还可以选择将其转换为所需数据类型。

语法

JSON_VALUE(json_doc, path [RETURNING type] [on_empty] [on_error])

on_empty:
    {NULL | ERROR | DEFAULT value} ON EMPTY

on_error:
    {NULL | ERROR | DEFAULT value} ON ERROR

说明

参数解释

相关参数解释如下：

• json_doc 参数指定有效的 JSON 文档。

• path 参数是指向文档中某个位置的 JSON 路径，必须是字符串。

• type 参数是支持如下数据类型：

  • FLOAT

  • DOUBLE

  • DECIMAL

  • SIGNED

  • UNSIGNED

  • DATE

  • TIME

  • DATETIME

  • YEAR (不支持 YEAR(1) 和 YEAR(2))

  • CHAR

  • JSON

• 如果没有使用 RETURNING 子句，则该函数的返回类型为 VARCHAR(512)。 当没有为返回类型指定字符集时，JSON_VALUE() 使用 utf8mb4 和二进制排序规则，并区分大小写； 如果将 utf8mb4 指定为结果的字符集，则服务器使用此字符集的默认排序规则，不用区分大小写。

• 当在指定路径中未找到数据时，on_empty 子句用于指定 JSON_VALUE() 的行为。该子句取值如下：

  • NULL ON EMPTY：JSON_VALUE() 返回 NULL。这是 ON EMPTY 的默认行为。

  • DEFAULT value ON EMPTY'：返回所提供的 value 值，该值的类型必须与返回类型相匹配。

  • ERROR ON EMPTY：函数抛出错误。

• 当发生错误时，on_error 取值如下：

  • NULL ON ERROR：JSON_VALUE() 返回 NULL；如果未使用 ON ERROR 子句，则这是默认行为。

  • DEFAULT value ON ERROR：返回所提供的 value 值，该值的类型必须与返回类型的值相匹配。

  • ERROR ON ERROR：抛出错误。

  注意

  ON EMPTY 的位置（如果使用）必须在所有 ON ERROR 子句之前，错误的顺序会导致语法错误。

错误处理

通常，JSON_VALUE() 会检查所有 JSON 输入（文档和路径）的有效性。如果其中任何一个为无效，则会抛出 SQL 错误，而不触发 ON ERROR 子句。

如果发生以下某一事件，就会触发 ON ERROR：

• 尝试提取对象或数组时，输入的路径在 JSON 文档中被解析为多个路径。

• 转换错误。例如，尝试将 'asdf' 转换为 UNSIGNED 值。

• 数据截断。

即使指定了 NULL ON ERROR 或 DEFAULT ... ON ERROR，转换错误总是会触发告警。

当源 JSON 文档 (json_doc) 在指定位置（path）不包含任何数据时，会触发 ON EMPTY 子句。

示例

obclient> SELECT JSON_VALUE('{"fname": "Smith", "lname": "Will"}', '$.fname');
+--------------------------------------------------------------+
| JSON_VALUE('{"fname": "Smith", "lname": "Will"}', '$.fname') |
+--------------------------------------------------------------+
| Smith                                                        |
+--------------------------------------------------------------+
1 row in set

obclient> SELECT JSON_VALUE('{"item": "shoes", "price": "69.73"}', '$.price'
     RETURNING DECIMAL(4,2)) AS price;
+-------+
| price |
+-------+
| 69.73 |
+-------+
1 row in set