大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:JSON_EXTRACT

· 52CE 我爱测

任一参数为 ,或所有路径均没有匹配值时,返回 SQL 。 - : 返回 指向的 JSON 元素,如果匹配了多个结果会以 JSON 数组的形式返回。

描述

从 JSON 类型的数据中提取 json_path 指定的字段。

语法

JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])

参数

参数 描述
<json_object> 必需。JSON 值,或可转换为 JSON 的合法 JSON 字符串。
<path> 必需。STRING 类型的 JSON 路径;数组遍历使用显式通配符。
<path2>, ... 可选。其他 STRING 类型路径;匹配结果组合为 JSON 数组。

返回值

任一参数为 NULL,或所有路径均没有匹配值时,返回 SQL NULL。

  • Nullable(JSON): 返回 <path> 指向的 JSON 元素,如果匹配了多个结果会以 JSON 数组的形式返回。

使用说明

  • 如果 <json_object> 是 NULL,或者 <path> 是 NULL,返回 NULL。

  • 对于单个 <path> 参数的情况,如果 <path> 如果路径不存在,返回 NULL。

  • 对于多个 <path> 参数的情况,如果所有字段都不在 JSON 中,返回 NULL;否则跳过不存在的字段,将匹配到的元素组成 JSON 数组返回。

  • 如果 <path> 不是一个合法的路径,报错。

  • 如果 <path> 对应的值是字符串,返回的字符串会被双引号(")包围,如果要得到没有双引号的结果,请对结果使用函数 JSON_UNQUOTE 以去掉双引号。

  • <path> 的语法如下

    • $ 代表 json root
    • .k1 代表 json object 中 key 为k1的元素
      • 如果 key 列值包含 ".", <path> 中需要用双引号,例如 SELECT json_extract('{"k1.a":"abc","k2":300}', '$."k1.a"');
    • [i] 代表 json array 中下标为 i 的元素
      • 获取 json_array 的最后一个元素可以用$[last],倒数第二个元素可以用$[last-1],以此类推。
    • * 代表通配符,即 $.* 代表根对象的所有成员,$[*] 代表数组的所有元素。
    • ** 代表通配符,通常和 '$' 一起使用: '$**' 代表所有的路径(以及多层的子路径,见下面的示例 9)。
  • 如果 <path> 存在通配符(*),匹配的结果会以数组形式返回。

  • <path> 不会在数组上自动广播。如果 <json_object> 是 JSON 数组,<path> 为 $.k,结果为 NULL —— $.k 只会遍历 object 的成员。要按下标访问元素,使用 $[i].k;要从数组的每个元素中提取字段,使用通配符语法 $[*].k,该语法自 Doris 4.0 起支持。

示例

  1. 一般参数
    SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
    

```text
+-----------------------------------------------+
    | JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
    +-----------------------------------------------+
    | "v31"                                         |
    +-----------------------------------------------+
    ```
    > 注意:返回的结果是`"v31"` 不是 `v31`。
2. NULL 参数
    ```sql
    select JSON_EXTRACT(null, '$.k1');
    ```
    ```text
    +----------------------------+
    | JSON_EXTRACT(null, '$.k1') |
    +----------------------------+
    | NULL                       |
    +----------------------------+
    ```
3. `<path>` 为 NULL
    ```sql
    SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
    ```
    ```text
    +---------------------------------------------+
    | JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
    +---------------------------------------------+
    | NULL                                        |
    +---------------------------------------------+
    ```
4. 多级路径
    ```sql
    SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key');
    ```
    ```text
    +------------------------------------------------------------------------+
    | JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
    +------------------------------------------------------------------------+
    | 1234.56                                                                |
    +------------------------------------------------------------------------+
    ```
5. 数组路径
    ```sql
    SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
    ```
    ```text
    +----------------------------------------------------------------------+
    | JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$.[2]') |
    +----------------------------------------------------------------------+
    | "2025-07-16 18:35:25"                                                |
    +----------------------------------------------------------------------+
    ```
6. 不存在的 path
    ```sql
    SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
    ```
    ```text
    +-----------------------------------------------+
    | JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
    +-----------------------------------------------+
    | NULL                                          |
    +-----------------------------------------------+
    ```
7. 多个路径参数
    ```sql
    select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id', '$.not_exists');
    ```
    ```text
    +--------------------------------------------------------------------------------+
    | JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id', '$.not_exists') |
    +--------------------------------------------------------------------------------+
    | ["doris",123]                                                                  |
    +--------------------------------------------------------------------------------+
    ```
    > 即使只有一个匹配也会以数组形式返回
    ```sql
    SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
    ```
    ```text
    +-----------------------------------------------------------------+
    | json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
    +-----------------------------------------------------------------+
    | ["doris"]                                                       |
    +-----------------------------------------------------------------+
    ```
    ```sql
    > 如果所有路径都没有匹配则返回 NULL
    select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2', '$.not_exists');
    ```
    ```text
    +------------------------------------------------------------------------------+
    | JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2', '$.not_exists') |
    +------------------------------------------------------------------------------+
    | NULL                                                                         |
    +------------------------------------------------------------------------------+
    ```

8. 通配符路径
    ```sql
    select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
    ```
    ```text
    +----------------------------------------------+
    | json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
    +----------------------------------------------+
    | [1,2,3,4,5]                                  |
    +----------------------------------------------+
    ```
    ```sql
    select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}', '$.*', '$.k3.k4');
    ```
    ```text
    +---------------------------------------------------------------------------------------+
    | json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}', '$.*', '$.k3.k4') |
    +---------------------------------------------------------------------------------------+
    | [[1,2,3,4,5],"abc",{"k4":"v4"},"v4"]                                                  |
    +---------------------------------------------------------------------------------------+
    ```
9. '**' 作为通配符
    ```sql
    select json_extract('{"k": 123, "b": {"k": ["ab", "cd"]}}', '$**.k');
    ```
    ```text
    +---------------------------------------------------------------+
    | json_extract('{"k": 123, "b": {"k": ["ab", "cd"]}}', '$**.k') |
    +---------------------------------------------------------------+
    | [123,["ab","cd"]]                                             |
    +---------------------------------------------------------------+
    ```
10. Value 是 NULL 的情况
    ```sql
    select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v, JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
    ```
    ```text
    +------+------+
    | v    | v2   |
    +------+------+
    | null |    0 |
    +------+------+
    ```

11. 从 JSON 数组的每个元素中提取字段(Doris 4.0+)
    ```sql
    select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
    ```
    ```text
    +--------------------------------------------------+
    | json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
    +--------------------------------------------------+
    | NULL                                             |
    +--------------------------------------------------+
    ```
    > `$.k` 不会遍历数组,只会下钻到对象的成员。
    ```sql
    select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
    ```
    ```text
    +-----------------------------------------------------+
    | json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
    +-----------------------------------------------------+
    | [1,2,3]                                             |
    +-----------------------------------------------------+
    ```
    > 使用 `$[*].k` 从数组的每个元素提取字段。

### 提取数组中的同名字段(Doris 4.0 及后续版本)

使用 `$[*].k1` 显式遍历数组元素;`$.k1` 只访问对象成员,不会隐式遍历数组,因此下面的直接路径返回 SQL `NULL`。没有 `k1` 的数组元素会被忽略。
```sql
SELECT json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]', '$.k1') AS direct_path,
       json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]', '$[*].k1') AS all_values;
+-------------+------------------+
| direct_path | all_values       |
+-------------+------------------+
| NULL        | ["v1","v3","v4"] |
+-------------+------------------+

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。