2203F — sql_json_scalar_required

JSON_VALUE 要求标量，收到的项不是标量。

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

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

12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Data Exception
condition name: sql_json_scalar_required
lang: en
sqlstate: 2203F

版本定义 PG 18

2203F

速览 {#at-a-glance}

JSON_VALUE 收到一个项，但该项不是标量。多个项会在更早的 22034 基数分支处理；空结果则由空结果/ON EMPTY 路径处理。

报文 {#messages}

固定的 JSON_VALUE 标量检查条件使用以下首要报文形式：

| 上下文 | 首要报文 | | --- | --- | | JSON_VALUE 映射到命名列 | JSON path expression for column "%s" must return single scalar item | | 独立 JSON_VALUE | JSON path expression in JSON_VALUE must return single scalar item |

含义 {#meaning}

JsonPathValue 先执行路径并标记空结果。多个项属于独立的 22034 基数分支。恰好一个项时，它会在必要时解开标量 JSON 容器，然后要求结果是 JSON 标量；对象或数组会进入 2203F。如果调用方为 ON ERROR 提供了错误指针，函数会设置错误标志并返回 NULL，而不是直接抛错。普通 ERROR 路径会报告上面按列名区分或不带列名的首要报文。

诊断 {#diagnosis}

检查 JSON_VALUE 路径结果的项数和选中项类型。空结果、多个项、单个非标量项分别属于不同分支，处理方式也不同。修改源 JSON 前先检查列映射以及 ON EMPTY/ON ERROR 子句，并把 JSON_QUERY 的包装语义与 JSON_VALUE 的标量要求区分开。

处理 {#response}

让路径解析为一个标量；如果业务确实需要对象或数组，改用合适的 SQL/JSON 操作；对预期缺失则配置文档规定的空值/错误处理。不要为了让集合看起来像标量而给 JSON_VALUE 添加包装。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

版本 {#versions}

锁定目录从 12.0 起记录该条件；固定的 JSON_VALUE 基数和标量检查来自 PostgreSQL 18.6。本页未声称有自然运行观察。

来源 {#sources}

JSON_VALUE 完整的空结果、多个项、标量和 ON ERROR 指针分支见 jsonpath_exec.c#L3991-4067。结构化证据记录绑定 22034 边界和两种 2203F 首要报文；本页未运行自然案例。

比较版本

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

claims · identity

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

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read the complete JsonPathValue empty, multiple-item, scalar-type, and error-pointer branches.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.value-cardinality"
  ],
  "statement": "The fixed JSON_VALUE executor marks an empty result before cardinality checks, reports 22034 for more than one item, and then requires the single remaining item to be a JSON scalar; a non-scalar item reaches 2203F. When an error pointer is supplied for ON ERROR handling, the function sets the error flag and returns NULL instead of throwing; the ordinary path emits the column-aware or column-less primary."
}

claims · history

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

messages · message.scalar-column

{
  "limits": "",
  "message_id": "message.scalar-column",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.scalar-column",
    "primary_template": "JSON path expression for column \"%s\" must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.value-cardinality"
    ],
    "sqlstate": "2203F"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.value-cardinality"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "JSON path expression for column \" \" must return single scalar item",
      "position": 0,
      "role": "",
      "template": "JSON path expression for column \"%s\" must return single scalar item"
    }
  ]
}

messages · message.scalar-no-column

{
  "limits": "",
  "message_id": "message.scalar-no-column",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.scalar-no-column",
    "primary_template": "JSON path expression in JSON_VALUE must return single scalar item",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.value-cardinality"
    ],
    "sqlstate": "2203F"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.value-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#L230"
}

sources · src.jsonpath.value-cardinality

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

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:f785a0bb8848c85bc5bd05f28f701eb7ba9abd7002c0fd32376d486d8243b326

正文语言: zh-Hans · english-manuals:f785a0bb8848c85bc5bd05f28f701eb7ba9abd7002c0fd32376d486d8243b326