---
title: "JSON_VALUE - OceanBase 数据库 V4.5.0 | OceanBase 文档中心"
description: "JSON_VALUE 描述 该函数从指定路径中提取 JSON 文档中的值，并返回提取的值，还可以选择将其转换为所需数据类型。 语法 JSON_VALUE(json_doc, path [RETURNING type] [on_empty] [on_error]) on_empty: {NULL | ERROR | D…"
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.5.0

# JSON_VALUE

更新时间：2026-03-19 15:29:21

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.5.0/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/400.functions-of-mysql-mode/700.json-functions-of-mysql-mode/200.search-json-text-function-of-mysql-mode/700.json-value-of-mysql-mode.md)  

## 描述

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

## 语法

```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 文档。
 - `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` 子句。

## 示例

```sql
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

```

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线