文档中心

JSON_VALUE ​

功能描述 ​

在给定的路径中获取一个值，并可选择返回类型将其转换返回。

语法格式 ​

sql
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文档，如果为NULL，表达式则返回NULL。

  • path：JSON路径，必须为字符串, 如果为NULL，表达式则返回null。

  • type：可以是以下基础类型。

    • CHAR
    • VARCHAR
    • BOOLEAN
    • TINYINT
    • SMALLINT
    • INTEGER
    • BIGINT
    • FLOAT
    • DOUBLE
    • NUMERIC
    • DATE
    • TIME
    • DATETIME
    • JSON

  • on_empty：如果在表达式使用，则当表达式没有查找到数据时指定表达式的行为，可以是如下列表。

    • NULL ON EMPTY：返回NULL；这也是默认的ON EMPTY行为。
    • DEFAULT value ON EMPTY：返回value值，且value值需与返回类型转换。
    • ERROR ON EMPTY：表达式抛出错误。

  • on_error：如果在表达式使用，则当表达式出现错误时指定表达式的行为，可以是如下列表。

    • NULL ON ERROR：返回NULL；这也是默认的ON ERROR行为。
    • DEFAULT value ON ERROR：返回value值，且value值需与返回类型转换。
    • ERROR ON ERROR：表达式抛出错误。

备注 ​

ON EMPTY必须在ON_ERROR子句之前使用，顺序错误会导致表达式抛出语法错误。

错误处理： ​

当json_doc或jsonpath其中一个无效，则SQL错误抛出而不触发ON ERROR规则。

ON ERROR触发规则 ​

  • 尝试提取对象或数组，例如从JSON多个路径位置生成对象和数组。
  • 转换错误，例如字符串“abc”转换为数值型。
  • 值的截断。

转换错误总会发送警告消息，即使指定不抛出错误，例如：{ default value | null } on error。

ON EMPTY触发规则 ​

当按照指定的路径无法找到值时触发。