22034 — more_than_one_sql_json_item
22034
速览
操作要求单个 SQL/JSON 项却得到多个项。固定 JSON_QUERY/JSON_VALUE 路径报告必须是单项或单标量，并可能提示使用 WITH WRAPPER。
| 字段 | 值 |
|---|---|
| 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 |
| 别名 | — |
报文
无 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 |
含义
固定的 JSON_QUERY 路径会收集完整 SQL/JSON 结果列表，并在应用 wrapper 模式前统计数量。没有 wrapper 时返回多个项会报告 22034；无条件或条件 WITH WRAPPER 会按模式把序列变成数组。JSON_VALUE 返回多个项时也使用本码，因为它要求单个标量。恰好一个非标量项属于独立的 2203F，零项则设置 empty 标志并交给 ON EMPTY 处理。lax 的自动展开可能改变结果基数；silent 或非 ERROR 的 ON ERROR 行为可能在基数守卫之前抑制求值错误。
诊断
记录操作类型（JSON_QUERY 或 JSON_VALUE）、wrapper 子句、列名以及 path 产生的项数。JSON_QUERY 只有在确实需要数组结果时才使用 WITH WRAPPER；JSON_VALUE 应将 path 缩减为单个标量。区分多个项（22034）、单个非标量项（2203F）和由 ON EMPTY/22035 处理的无项结果。检查 strict/lax 和 silent 设置，因为它们会影响守卫看到的结果序列。
处理
修改 path 或过滤条件，使其返回所需的单个项；如果消费方需要数组，则加入文档规定的 wrapper。对 JSON_VALUE 还要确保该项是标量。如果操作使用 ON ERROR 行为，应使回退值符合预期基数，不要把 NULL 误当成 path 返回了单个项。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的表达式。
版本
锁定目录从 12.0 起记录该条件；本页固定 SQL/JSON 基数源码路径为 PostgreSQL 18.6。未声称本页有自然运行观察。
相关
来源
JSON_QUERY wrapper 和多项守卫见 src/backend/utils/adt/jsonpath_exec.c#L3880-4005。JSON_VALUE 的多项与标量区分见 #L4008-4070。结构化证据记录保留 wrapper、基数和提示角色；本页未运行自然案例。