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

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

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

22038 singleton_sql_json_item_required

ERROR 源码确认 参考 未实测

类别
Class 22 数据异常
严重等级
ERROR
条件名
singleton_sql_json_item_required
宏名称
ERRCODE_SINGLETON_SQL_JSON_ITEM_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

速览

SQL/JSON 路径操作要求一个特定类型的单一结果，却收到了不同的基数或类型。固定路径覆盖单一布尔结果，以及 jsonpath 二元算术的左右两个数值操作数；SQL 函数和 @@ 操作符的 silent 默认行为不同。

报文

代表性首要报文如下：

触发条件 首要报文
抛错模式下 jsonb_path_match 的结果不是单一布尔项 single boolean result is expected
二元算术左操作数不是一个数值项 left operand of jsonpath operator %s is not a single numeric value
二元算术右操作数不是一个数值项 right operand of jsonpath operator %s is not a single numeric value

报文模板

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

主消息 single boolean result is expected

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

主消息 left operand of jsonpath operator %s is not a single numeric value

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

主消息 right operand of jsonpath operator %s is not a single numeric value

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

含义

jsonb_path_match_internal 把恰好两个 C 参数识别为 @@ 操作符路径：jsonb_path_match_opr 保持 silent=true，所以结果不是单一布尔项时返回 NULL。SQL 函数声明为 jsonb_path_match(target, path, vars DEFAULT '{}', silent DEFAULT false)；即使 SQL 调用只写两个参数，两个默认参数也会补齐，因此它是非 silent 的，除非调用者显式传入 silent=true，否则可能报告 22038。四参数调用遵循实际传入的 silent 值。单个 JSON null 会返回 SQL NULL。二元算术则分别计算左右操作数序列，两边都必须恰好包含一个数值项。共享执行器在 lax 模式下可能先解包数组，再进行单项检查。

诊断

先确认语法使用的是 @@ 操作符还是 jsonb_path_match 函数，并检查实际参数及默认参数展开，之后再解释 NULL 结果。路径产生多个值、match 结果不是布尔值，或左右项不是数值，都属于这个单项/类型边界。将其与 JSON_QUERY/JSON_VALUE 基数错误 22034、标量类型约束 2203F，以及数值项方法转换错误 22036 区分开。

处理

收窄路径或明确选取一个项。二元算术应确保左右操作数各自解析为一个数值项；如果确实需要抑制错误可使用 @@，如果希望不匹配仍报告 ERROR 则调用 jsonb_path_match(..., false)；只有业务确实要返回 NULL 时才传入 silent=true。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

版本

锁定目录从 12.0 起记录该条件；固定的 match 和二元算术路径来自 PostgreSQL 18.6。本页未声称有自然运行观察。

来源

证据

断言

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

同类错误代码

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