22034 — more_than_one_sql_json_item

SQL/JSON 结果多于一项，需要单项。

英文手册覆盖始于 PostgreSQL 8.1. 来源历史与运行验证各自保留独立版本边界。

当前阅读 PG 18·选择有来源记录的版本

12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Data Exception
condition name: more_than_one_sql_json_item
lang: en
sqlstate: 22034

版本定义 PG 18

22034

速览 {#at-a-glance}

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

报文 {#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。未声称本页有自然运行观察。

来源 {#sources}

JSON_QUERY wrapper 和多项守卫见 src/backend/utils/adt/jsonpath_exec.c#L3880-4005。JSON_VALUE 的多项与标量区分见 #L4008-4070。结构化证据记录保留 wrapper、基数和提示角色；本页未运行自然案例。

比较版本

SQLSTATE 证据与已记录的运行版本

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22034 is more_than_one_sql_json_item in SQLSTATE Class 22."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read JsonPathQuery and JsonPathValue cardinality, wrapper, and scalar guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.jsonpath.cardinality"
  ],
  "statement": "The fixed JSON_QUERY path collects the complete SQL/JSON result list, uses the wrapper mode to permit multiple items, and emits 22034 only when more than one item remains without a wrapper; JSON_VALUE uses the same code for more than one item, while a single non-scalar is the separate 2203F condition."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22034 from 12.0 without proving exact implementation introduction."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "hint_template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
    "id": "message.0",
    "primary_template": "JSON path expression for column \"%s\" must return single item when no wrapper is requested",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression for column \" \" must return single item when no wrapper is requested",
      "position": 0,
      "role": "",
      "template": "JSON path expression for column \"%s\" must return single item when no wrapper is requested"
    },
    {
      "kind": "hint",
      "literal": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
      "position": 1,
      "role": "",
      "template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array."
    }
  ]
}

messages · message.json-query

{
  "limits": "",
  "message_id": "message.json-query",
  "path": "",
  "position": 1,
  "raw": {
    "hint_template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
    "id": "message.json-query",
    "primary_template": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.cardinality"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested",
      "position": 0,
      "role": "",
      "template": "JSON path expression in JSON_QUERY must return single item when no wrapper is requested"
    },
    {
      "kind": "hint",
      "literal": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.",
      "position": 1,
      "role": "",
      "template": "Use the WITH WRAPPER clause to wrap SQL/JSON items into an array."
    }
  ]
}

messages · message.json-value

{
  "limits": "",
  "message_id": "message.json-value",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.json-value",
    "primary_template": "JSON path expression in JSON_VALUE must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.cardinality"
    ],
    "sqlstate": "22034"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression in JSON_VALUE must return single scalar item",
      "position": 0,
      "role": "",
      "template": "JSON path expression in JSON_VALUE must return single scalar item"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L219"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonpath_exec.c",
  "position": 1,
  "sha256": "678cb8947f0b5e6ad14524f1863987ab99641cfb5f81121fc5c5006af0319d02",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3966"
}

sources · src.jsonpath.cardinality

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonpath_exec.c",
  "position": 2,
  "sha256": "678cb8947f0b5e6ad14524f1863987ab99641cfb5f81121fc5c5006af0319d02",
  "source_id": "src.jsonpath.cardinality",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3880"
}

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:00c46b2af84dfc515da2ba5cc0c1864d9c90fc7b3ab0f2a6b9eb20ca49e73b1a

正文语言: zh-Hans · english-manuals:00c46b2af84dfc515da2ba5cc0c1864d9c90fc7b3ab0f2a6b9eb20ca49e73b1a