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

Apache Doris 中文参考:PARSE_TO_VARIANT

· 52CE 我爱测

将一个完整 JSON 值解析为 ,支持 JSON 对象、数组、字符串、数字、布尔值和 JSON 字面量 。该函数自 Doris 4.1.4 起支持;本页描述的是 Doris 5.0.0 及之后版本中的行为。

功能

PARSE_TO_VARIANT 将一个完整 JSON 值解析为 VARIANT,支持 JSON 对象、数组、字符串、数字、布尔值和 JSON 字面量 null。该函数自 Doris 4.1.4 起支持;本页描述的是 Doris 5.0.0 及之后版本中的行为。

语法

PARSE_TO_VARIANT(<json_value>)

参数

参数 说明
<json_value> 包含一个完整 JSON 值的 CHAR、VARCHAR 或 STRING 表达式,也可以是 JSON/JSONB 表达式。JSON/JSONB 输入会先转换为 JSON 文本,再解析为 VARIANT。

返回值

返回 VARIANT 值。

  • 输入为 SQL NULL 时返回 SQL NULL。
  • 输入为 JSON 字面量 null 时返回 VARIANT null,它与 SQL NULL 不同。
  • 非法 JSON 文本会作为 VARIANT 字符串返回;包含超出 [-2^63, 2^64 - 1] 的整数或超出 DOUBLE 范围的数值的 JSON 也是如此,整段文本变为一个字符串。该行为由 BE 配置 variant_throw_exeception_on_invalid_json(默认 false)控制;设置为 true 后,这类输入会使查询失败。
  • 输入为空字符串时返回空对象 {}。
  • 嵌套深到 JSON 解析器本身拒绝的文档(约 1000 层)属于非法 JSON,同样作为字符串返回。
  • 以下情况查询失败:对象 key 超过 variant_max_json_key_length 字节(BE 配置,默认 255);同一对象中有重复 key(BE 配置 variant_enable_duplicate_json_path_check 为 true 时保留第一个值,不报错);嵌套超过 128 层;字符串不是合法的 UTF-8。

示例

解析 JSON 文本:

SELECT CAST(
           PARSE_TO_VARIANT('{"id": 42, "tags": ["doris", "sql"]}')
           AS STRING
       ) AS value;
+----------------------------------+
| value                            |
+----------------------------------+
| {"id":42,"tags":["doris","sql"]} |
+----------------------------------+

解析 JSON/JSONB 表达式:

SELECT CAST(
           PARSE_TO_VARIANT(CAST('{"id": 42}' AS JSON))
           AS STRING
       ) AS value;
+-----------+
| value     |
+-----------+
| {"id":42} |
+-----------+

提取值并 CAST 为具体 SQL 类型:

SELECT CAST(
           PARSE_TO_VARIANT('{"user": {"id": 42}}')['user']['id']
           AS BIGINT
       ) AS user_id;
+---------+
| user_id |
+---------+
|      42 |
+---------+

SQL NULL 仍返回 SQL NULL:

SELECT PARSE_TO_VARIANT(NULL) IS NULL AS is_sql_null;
+-------------+
| is_sql_null |
+-------------+
|           1 |
+-------------+

非法 JSON 文本会保留为字符串:

SELECT CAST(PARSE_TO_VARIANT('{"id":') AS STRING) AS value,
       VARIANT_TYPE(PARSE_TO_VARIANT('{"id":'))    AS type;
+--------+--------+
| value  | type   |
+--------+--------+
| {"id": | string |
+--------+--------+

重复 key 会报错:

SELECT PARSE_TO_VARIANT('{"id": 1, "id": 2}');
ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]Parse json document failed at row 0, error: [INVALID_ARGUMENT]Duplicate Variant object key

使用说明

  • 如果希望解析错误返回 SQL NULL 而不是使查询失败,请使用 TRY_PARSE_TO_VARIANT。
  • PARSE_TO_VARIANT 会显式解析 JSON。相比之下,CAST(string AS VARIANT) 以及通过 INSERT 把字符串写入 VARIANT 列,都会把输入保留为 VARIANT 字符串,不解析 JSON。用 INSERT 写入 JSON 文本时,请用 PARSE_TO_VARIANT 包裹。详见写入数据与其他类型 CAST 为 VARIANT。

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

资料来源与适用范围

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

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

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