# 2203F — sql_json_scalar_required

> PostgreSQL SQLSTATE 2203F 的来源与诊断参考。
---

# 2203F

## 速览 {#at-a-glance}
JSON_VALUE 收到一个项，但该项不是标量。多个项会在更早的 22034 基数分支处理；空结果则由空结果/ON EMPTY 路径处理。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| 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` |
| 别名 | `—` |

<!-- source facts: data/errcodes/2203F.json -->
<!-- END SQLSTATE FACTS -->

## 报文 {#messages}
固定的 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` |

## 含义 {#meaning}
`JsonPathValue` 先执行路径并标记空结果。多个项属于独立的 22034 基数分支。恰好一个项时，它会在必要时解开标量 JSON 容器，然后要求结果是 JSON 标量；对象或数组会进入 2203F。如果调用方为 ON ERROR 提供了错误指针，函数会设置错误标志并返回 NULL，而不是直接抛错。普通 ERROR 路径会报告上面按列名区分或不带列名的首要报文。

## 诊断 {#diagnosis}
检查 JSON_VALUE 路径结果的项数和选中项类型。空结果、多个项、单个非标量项分别属于不同分支，处理方式也不同。修改源 JSON 前先检查列映射以及 ON EMPTY/ON ERROR 子句，并把 JSON_QUERY 的包装语义与 JSON_VALUE 的标量要求区分开。

## 处理 {#response}
让路径解析为一个标量；如果业务确实需要对象或数组，改用合适的 SQL/JSON 操作；对预期缺失则配置文档规定的空值/错误处理。不要为了让集合看起来像标量而给 JSON_VALUE 添加包装。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

## 版本 {#versions}
锁定目录从 12.0 起记录该条件；固定的 JSON_VALUE 基数和标量检查来自 PostgreSQL 18.6。本页未声称有自然运行观察。

## 相关 {#related}
[`22034`](../22034/)、[`22035`](../22035/)、[`22036`](../22036/)

## 来源 {#sources}
JSON_VALUE 完整的空结果、多个项、标量和 ON ERROR 指针分支见 [`jsonpath_exec.c#L3991-4067`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3991)。结构化[证据记录](../../data/evidence/2203f.json)绑定 22034 边界和两种 2203F 首要报文；本页未运行自然案例。