22038 — singleton_sql_json_item_required
22038
速览
SQL/JSON 路径操作要求一个特定类型的单一结果，却收到了不同的基数或类型。固定路径覆盖单一布尔结果，以及 jsonpath 二元算术的左右两个数值操作数；SQL 函数和 @@ 操作符的 silent 默认行为不同。
| 字段 | 值 |
|---|---|
| SQLSTATE | 22038 |
| 条件名 | singleton_sql_json_item_required |
| 状态 | 有效 |
| 已知存在于 | 12.0 |
| 锁定快照 | 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3 |
| 宏 | ERRCODE_SINGLETON_SQL_JSON_ITEM_REQUIRED |
| 别名 | — |
报文
代表性首要报文如下：
| 触发条件 | 首要报文 |
|---|---|
抛错模式下 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 |
含义
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。本页未声称有自然运行观察。
相关
来源
match 包装器和单项检查见 jsonpath_exec.c#L453-491；二元算术单项检查见 #L2087-2155；共享的 strict/lax 与抛出/返回宏见 #L235-249。SQL 默认参数固定在 system_functions.sql#L539-544，函数和 @@ 实现签名见 pg_proc.dat#L10520-10522 与 #L10547-10549，操作符绑定见 pg_operator.dat#L3262-3264。结构化证据记录保留两条路径和准确首要报文；本页未运行自然案例。