# 22038 — singleton_sql_json_item_required

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

# 22038

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

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

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

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

## 报文 {#messages}
代表性首要报文如下：

| 触发条件 | 首要报文 |
| --- | --- |
| 抛错模式下 `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` |

## 含义 {#meaning}
`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 模式下可能先解包数组，再进行单项检查。

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

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

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

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

## 来源 {#sources}
match 包装器和单项检查见 [`jsonpath_exec.c#L453-491`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L453)；二元算术单项检查见 [`#L2087-2155`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L2087)；共享的 strict/lax 与抛出/返回宏见 [`#L235-249`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L235)。SQL 默认参数固定在 [`system_functions.sql#L539-544`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/catalog/system_functions.sql#L539)，函数和 `@@` 实现签名见 [`pg_proc.dat#L10520-10522`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_proc.dat#L10520) 与 [`#L10547-10549`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_proc.dat#L10547)，操作符绑定见 [`pg_operator.dat#L3262-3264`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_operator.dat#L3262)。结构化[证据记录](../../data/evidence/22038.json)保留两条路径和准确首要报文；本页未运行自然案例。