22038 — singleton_sql_json_item_required

SQL/JSON 路径要求单一指定类型的结果。

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

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

12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Data Exception
condition name: singleton_sql_json_item_required
lang: en
sqlstate: 22038

版本定义 PG 18

22038

速览 {#at-a-glance}

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

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

来源 {#sources}

match 包装器和单项检查见 jsonpath_exec.c#L453-491；二元算术单项检查见 #L2087-2155；共享的 strict/lax 与抛出/返回宏见 #L235-249。SQL 默认参数固定在 system_functions.sql#L539-544，函数和 @@ 实现签名见 pg_proc.dat#L10520-10522 与 #L10547-10549，操作符绑定见 pg_operator.dat#L3262-3264。结构化证据记录保留两条路径和准确首要报文；本页未运行自然案例。

比较版本

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

claims · identity

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

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read jsonb_path_match_internal together with system function defaults, pg_proc signatures, the @@ operator binding, and the shared jsonpath evaluator.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.match-singleton",
    "src.jsonpath.binary-arithmetic-singleton",
    "src.jsonpath.context-flags",
    "src.jsonpath.execute-context",
    "src.catalog.system-functions",
    "src.catalog.pg-proc-match",
    "src.catalog.pg-proc-match-opr",
    "src.catalog.pg-operator-match"
  ],
  "statement": "The fixed jsonb_path_match_internal path treats exactly two C arguments as the @@ operator call: jsonb_path_match_opr leaves silent=true, so a non-singleton or non-boolean result is suppressed to NULL. The SQL function jsonb_path_match has vars DEFAULT '{}' and silent DEFAULT false; even a call written with two SQL arguments is expanded with both defaults, so it is non-silent unless silent=true is explicitly supplied. Binary jsonpath arithmetic independently requires each operand sequence to contain exactly one numeric item; lax unwrapping is performed by the shared evaluator."
}

claims · history

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

messages · message.boolean-singleton

{
  "limits": "",
  "message_id": "message.boolean-singleton",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.boolean-singleton",
    "primary_template": "single boolean result is expected",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.match-singleton"
    ],
    "sqlstate": "22038"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.match-singleton"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "single boolean result is expected",
      "position": 0,
      "role": "",
      "template": "single boolean result is expected"
    }
  ]
}

messages · message.left-numeric-singleton

{
  "limits": "",
  "message_id": "message.left-numeric-singleton",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.left-numeric-singleton",
    "primary_template": "left operand of jsonpath operator %s is not a single numeric value",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.binary-arithmetic-singleton"
    ],
    "sqlstate": "22038"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.binary-arithmetic-singleton"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "left operand of jsonpath operator is not a single numeric value",
      "position": 0,
      "role": "",
      "template": "left operand of jsonpath operator %s is not a single numeric value"
    }
  ]
}

messages · message.right-numeric-singleton

{
  "limits": "",
  "message_id": "message.right-numeric-singleton",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.right-numeric-singleton",
    "primary_template": "right operand of jsonpath operator %s is not a single numeric value",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.binary-arithmetic-singleton"
    ],
    "sqlstate": "22038"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.binary-arithmetic-singleton"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "right operand of jsonpath operator is not a single numeric value",
      "position": 0,
      "role": "",
      "template": "right operand of jsonpath operator %s is not a single numeric value"
    }
  ]
}

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#L223"
}

sources · src.jsonpath.match-singleton

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

sources · src.jsonpath.binary-arithmetic-singleton

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

sources · src.jsonpath.context-flags

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

sources · src.jsonpath.execute-context

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

sources · src.catalog.system-functions

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/catalog/system_functions.sql",
  "position": 5,
  "sha256": "e5b61e70663b9dd55e2e6397ecb1ff3084f4f9afbf12907529b6e565a75f254f",
  "source_id": "src.catalog.system-functions",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/catalog/system_functions.sql#L539"
}

sources · src.catalog.pg-proc-match

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/include/catalog/pg_proc.dat",
  "position": 6,
  "sha256": "1f934ce80d460159dda137714374a35f9896315ea2476709cbb4da13b38ef95a",
  "source_id": "src.catalog.pg-proc-match",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_proc.dat#L10520"
}

sources · src.catalog.pg-proc-match-opr

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/include/catalog/pg_proc.dat",
  "position": 7,
  "sha256": "1f934ce80d460159dda137714374a35f9896315ea2476709cbb4da13b38ef95a",
  "source_id": "src.catalog.pg-proc-match-opr",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_proc.dat#L10547"
}

sources · src.catalog.pg-operator-match

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/include/catalog/pg_operator.dat",
  "position": 8,
  "sha256": "5d35b9b2ef5f9797cc815263927ef8a12367fedace53e828b4e8b320e2a7f703",
  "source_id": "src.catalog.pg-operator-match",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/catalog/pg_operator.dat#L3262"
}

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:5b84e8967d81c30953c66bad5e88ad21e0de7a2f7c203bfd6a8737eaa1a6c1ef

正文语言: zh-Hans · english-manuals:5b84e8967d81c30953c66bad5e88ad21e0de7a2f7c203bfd6a8737eaa1a6c1ef