2203F — sql_json_scalar_required
2203F
速览
JSON_VALUE 收到一个项，但该项不是标量。多个项会在更早的 22034 基数分支处理；空结果则由空结果/ON EMPTY 路径处理。
| 字段 | 值 |
|---|---|
| SQLSTATE | 2203F |
| 条件名 | sql_json_scalar_required |
| 状态 | 有效 |
| 已知存在于 | 12.0 |
| 锁定快照 | 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3 |
| 宏 | ERRCODE_SQL_JSON_SCALAR_REQUIRED |
| 别名 | — |
报文
固定的 JSON_VALUE 标量检查条件使用以下首要报文形式：
| 上下文 | 首要报文 |
|---|---|
| JSON_VALUE 映射到命名列 | JSON path expression for column "%s" must return single scalar item |
| 独立 JSON_VALUE | JSON path expression in JSON_VALUE must return single scalar item |
含义
JsonPathValue 先执行路径并标记空结果。多个项属于独立的 22034 基数分支。恰好一个项时，它会在必要时解开标量 JSON 容器，然后要求结果是 JSON 标量；对象或数组会进入 2203F。如果调用方为 ON ERROR 提供了错误指针，函数会设置错误标志并返回 NULL，而不是直接抛错。普通 ERROR 路径会报告上面按列名区分或不带列名的首要报文。
诊断
检查 JSON_VALUE 路径结果的项数和选中项类型。空结果、多个项、单个非标量项分别属于不同分支，处理方式也不同。修改源 JSON 前先检查列映射以及 ON EMPTY/ON ERROR 子句，并把 JSON_QUERY 的包装语义与 JSON_VALUE 的标量要求区分开。
处理
让路径解析为一个标量；如果业务确实需要对象或数组，改用合适的 SQL/JSON 操作；对预期缺失则配置文档规定的空值/错误处理。不要为了让集合看起来像标量而给 JSON_VALUE 添加包装。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。
版本
锁定目录从 12.0 起记录该条件；固定的 JSON_VALUE 基数和标量检查来自 PostgreSQL 18.6。本页未声称有自然运行观察。
相关
来源
JSON_VALUE 完整的空结果、多个项、标量和 ON ERROR 指针分支见 jsonpath_exec.c#L3991-4067。结构化证据记录绑定 22034 边界和两种 2203F 首要报文；本页未运行自然案例。