↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 错误代码 / Class 22 数据异常

2203F sql_json_scalar_required

ERROR 源码确认 参考 未实测

类别
Class 22 数据异常
严重等级
ERROR
条件名
sql_json_scalar_required
宏名称
ERRCODE_SQL_JSON_SCALAR_REQUIRED
启用版本
12
状态
活跃

版本覆盖

  1. 18
  2. 17
  3. 16
  4. 15
  5. 14
  1. 13
  2. 12
  3. 11
  4. 10
  1. 19 beta
  2. 20 dev

速览

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

报文

固定的 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

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 JSON path expression for column "%s" must return single scalar item

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

主消息 JSON path expression in JSON_VALUE must return single scalar item

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

含义

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。本页未声称有自然运行观察。

来源

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

  • 2203F is sql_json_scalar_required in SQLSTATE Class 22.

    核实方式Read fixed definition.

    来源src/backend/utils/errcodes.txt

  • The fixed JSON_VALUE executor marks an empty result before cardinality checks, reports 22034 for more than one item, and then requires the single remaining item to be a JSON scalar; a non-scalar item reaches 2203F. When an error pointer is supplied for ON ERROR handling, the function sets the error flag and returns NULL instead of throwing; the ordinary path emits the column-aware or column-less primary.

    核实方式Read the complete JsonPathValue empty, multiple-item, scalar-type, and error-pointer branches.

    不覆盖Source confirmation is not a natural runtime observation.

    来源src/backend/utils/adt/jsonpath_exec.c

  • The locked catalogue records 2203F from 12.0 without proving exact implementation introduction.

    核实方式Use catalogue boundary.

    来源src/backend/utils/errcodes.txt

同类错误代码

Class 22 数据异常 下的其他成员。