22039 — sql_json_array_not_found

JSON 路径访问器要求数组却收到非数组项。

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

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

12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Data Exception
condition name: sql_json_array_not_found
lang: en
sqlstate: 22039

版本定义 PG 18

22039

速览 {#at-a-glance}

只接受数组的 JSON 路径访问器或项方法在没有允许自动包装或结构错误抑制时收到了非数组项。固定的通配数组、索引数组和 .size() 路径分别有数组类型首要报文；越界下标属于 22033。

报文 {#messages}

代表性首要报文如下：

| 触发条件 | 首要报文 | | --- | --- | | 通配数组访问器收到非数组 | jsonpath wildcard array accessor can only be applied to an array | | 索引数组访问器收到非数组 | jsonpath array accessor can only be applied to an array | | .size() 在不允许自动包装时收到非数组 | jsonpath item method .%s() can only be applied to an array |

含义 {#meaning}

jpiAnyArray 通配入口、jpiIndexArray 索引入口和 .size() 项方法入口，在 lax 模式启用 jspAutoWrap(cxt) 时都可以把非数组项自动包装。未允许自动包装时，jspIgnoreStructuralErrors 可以抑制结构不匹配；两者都不适用时，相应的只接受数组分支才报告 22039。有效数组却使用越界下标会进入独立的 22033 下标检查条件，因此 22039 不表示空数组或下标越界。

诊断 {#diagnosis}

根据首要报文确认具体访问器或方法，并检查它前一步收到的项。区分标量/对象输入与有效数组的越界索引，同时确认 SQL/JSON 路径模式是否启用了 lax 结构错误处理或自动包装/解包。

处理 {#response}

让路径选出数组、规范化输入形状，或改用适用于标量的操作。如果文档可能同时出现标量和数组，应显式处理这两种分支，不要依赖结构不匹配变成空结果。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的动作。

版本 {#versions}

锁定目录从 12.0 起记录该条件；固定的数组访问和 .size() 检查条件来自 PostgreSQL 18.6。本页未声称有自然运行观察。

来源 {#sources}

通配、索引和自动包装检查见 jsonpath_exec.c#L836-979；.size() 数组检查见 #L1101-1117。strict/lax 结构处理和抛出/返回宏见 #L235-249。结构化证据记录绑定准确的数组报文和 22033 边界；本页未运行自然案例。

比较版本

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

claims · identity

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

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read the complete array wildcard/index and size-method guards, including structural-error suppression and the adjacent subscript boundary.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.jsonpath.array-accessors",
    "src.jsonpath.array-size",
    "src.jsonpath.context-flags",
    "src.jsonpath.execute-context"
  ],
  "statement": "The fixed jpiAnyArray wildcard, jpiIndexArray indexed accessor, and .size() item-method branches can each auto-wrap a non-array item when jspAutoWrap(cxt) is enabled by lax mode. If auto-wrap is not permitted, jspIgnoreStructuralErrors can suppress the structural mismatch; when neither applies, the corresponding array-only branch reports 22039. Array index out-of-bounds is a separate 22033 guard."
}

claims · history

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

messages · message.wildcard-array

{
  "limits": "",
  "message_id": "message.wildcard-array",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.wildcard-array",
    "primary_template": "jsonpath wildcard array accessor can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-accessors"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-accessors"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath wildcard array accessor can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath wildcard array accessor can only be applied to an array"
    }
  ]
}

messages · message.index-array

{
  "limits": "",
  "message_id": "message.index-array",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.index-array",
    "primary_template": "jsonpath array accessor can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-accessors"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-accessors"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath array accessor can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath array accessor can only be applied to an array"
    }
  ]
}

messages · message.size-array

{
  "limits": "",
  "message_id": "message.size-array",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.size-array",
    "primary_template": "jsonpath item method .%s() can only be applied to an array",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.array-size"
    ],
    "sqlstate": "22039"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.array-size"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "jsonpath item method . () can only be applied to an array",
      "position": 0,
      "role": "",
      "template": "jsonpath item method .%s() can only be applied to an array"
    }
  ]
}

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

sources · src.jsonpath.array-accessors

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

sources · src.jsonpath.array-size

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

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

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:5d026b11496ffcab3614f7a2e515e0f4dc036bf19a05743ee43087dd7561629d

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