# 22034 — more_than_one_sql_json_item

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

# 22034

## 速览 {#at-a-glance}
操作要求单个 SQL/JSON 项却得到多个项。固定 JSON_QUERY/JSON_VALUE 路径报告必须是单项或单标量，并可能提示使用 WITH WRAPPER。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22034` |
| 条件名 | `more_than_one_sql_json_item` |
| 状态 | `有效` |
| 已知存在于 | `12.0` |
| 锁定快照 | `12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_MORE_THAN_ONE_SQL_JSON_ITEM` |
| 别名 | `—` |

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

## 报文 {#messages}
无 wrapper 的基数守卫使用以下首要文本：

| 操作 | 首要文本和提示 |
| --- | --- |
| 无 wrapper 的 `JSON_QUERY` 列 | `JSON path expression for column "%s" must return single item when no wrapper is requested`；HINT：`Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.` |
| 没有列名的 `JSON_QUERY` | `JSON path expression in JSON_QUERY must return single item when no wrapper is requested`；HINT：`Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.` |
| `JSON_VALUE` 返回多个项 | `JSON path expression in JSON_VALUE must return single scalar item` |

## 含义 {#meaning}
固定的 JSON_QUERY 路径会收集完整 SQL/JSON 结果列表，并在应用 wrapper 模式前统计数量。没有 wrapper 时返回多个项会报告 22034；无条件或条件 `WITH WRAPPER` 会按模式把序列变成数组。JSON_VALUE 返回多个项时也使用本码，因为它要求单个标量。恰好一个非标量项属于独立的 2203F，零项则设置 empty 标志并交给 ON EMPTY 处理。lax 的自动展开可能改变结果基数；silent 或非 ERROR 的 ON ERROR 行为可能在基数守卫之前抑制求值错误。

## 诊断 {#diagnosis}
记录操作类型（`JSON_QUERY` 或 `JSON_VALUE`）、wrapper 子句、列名以及 path 产生的项数。JSON_QUERY 只有在确实需要数组结果时才使用 `WITH WRAPPER`；JSON_VALUE 应将 path 缩减为单个标量。区分多个项（22034）、单个非标量项（2203F）和由 ON EMPTY/22035 处理的无项结果。检查 strict/lax 和 silent 设置，因为它们会影响守卫看到的结果序列。

## 处理 {#response}
修改 path 或过滤条件，使其返回所需的单个项；如果消费方需要数组，则加入文档规定的 wrapper。对 JSON_VALUE 还要确保该项是标量。如果操作使用 ON ERROR 行为，应使回退值符合预期基数，不要把 NULL 误当成 path 返回了单个项。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的表达式。

## 版本 {#versions}
锁定目录从 12.0 起记录该条件；本页固定 SQL/JSON 基数源码路径为 PostgreSQL 18.6。未声称本页有自然运行观察。

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

## 来源 {#sources}
JSON_QUERY wrapper 和多项守卫见 [`src/backend/utils/adt/jsonpath_exec.c#L3880-4005`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3880)。JSON_VALUE 的多项与标量区分见 [`#L4008-4070`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L4008)。结构化[证据记录](../../data/evidence/22034.json)保留 wrapper、基数和提示角色；本页未运行自然案例。