22031 — invalid_argument_for_sql_json_datetime_function

SQL/JSON datetime 方法的参数或格式无效。

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

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

13 14 15 16 17 18 19 20

aliases: 未知
class name: Data Exception
condition name: invalid_argument_for_sql_json_datetime_function
lang: en
sqlstate: 22031

版本定义 PG 18

22031

速览 {#at-a-glance}

SQL/JSON datetime 方法收到无效类型、精度或格式。固定 jsonpath 执行路径报告无法识别的格式，并提示使用 datetime 模板参数。

报文 {#messages}

日期时间方法守卫使用以下首要文本：

| 守卫 | 首要文本和提示 | | --- | --- | | 输入项不是字符串 | jsonpath item method .%s() can only be applied to a string | | .datetime() 未识别格式 | %s format is not recognized: "%s"；HINT：Use a datetime template argument to specify the input data format. | | 精度超出整数范围 | time precision of jsonpath item method .%s() is out of range for type integer | | 调整后的精度无效 | time precision of jsonpath item method .%s() is invalid |

含义 {#meaning}

固定的 executeDateTimeMethod 路径首先要求输入是标量字符串。.datetime(template) 将显式模板交给 parse_datetime：当 jspThrowErrors(cxt) 为 false 时，ErrorSaveContext 会把解析失败转成 jperError；允许抛错时不传入保存上下文，解析器可能直接抛出底层错误。没有模板的 .datetime()、.date()、.time()、.time_tz()、.timestamp() 和 .timestamp_tz() 路径会按列出的 ISO 格式循环尝试，即使在抛错执行中也会把每个候选格式的失败软保存；所有候选都失败后，最终 22031 的 RETURN_ERROR 分支才决定抛错还是返回 jperError。可选时间精度先转换为整数并检查，再进行调整。格式无法识别、转换不兼容、输入不是字符串或精度无效时使用 22031。

诊断 {#diagnosis}

记录方法名、输入 JSON 项类型、日期时间文本、模板文本（如有）和精度参数。.datetime() 没有匹配格式时会提示提供模板；其他方法使用固定 ISO 候选格式，不提供该模板提示。分开判断标量类型不符、格式错误以及精度范围/调整错误。lax 控制结构上的自动包装/解包和结构错误处理，并不会普遍抑制日期时间解析或转换错误；应结合执行器的 throwErrors/RETURN_ERROR 路径，以及 jsonb_path_* 函数的 silent 参数或 SQL/JSON 的 ON ERROR 子句，判断保存的解析错误是被返回还是抛出。

处理 {#response}

向方法传入字符串项；对 .datetime() 使用与日期时间文本匹配的模板，或选择与输入相符的 ISO 类型方法。保持精度符合整数和日期时间 typmod 规则。如果应用有意使用非 ERROR 的 ON ERROR 行为处理解析失败，应按应用要求保留或修正该行为；否则修正输入或模板。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的表达式。

版本 {#versions}

锁定目录从 13.0 起记录该条件；本页固定 SQL/JSON 日期时间源码路径为 PostgreSQL 18.6。未声称本页有自然运行观察。

来源 {#sources}

日期时间方法实现见 src/backend/utils/adt/jsonpath_exec.c#L2326-2780，涵盖字符串/类型检查、显式模板和 ISO 候选解析、ErrorSaveContext、类型转换及精度守卫。strict/lax/throw 区分见 #L235-249 和 #L654-727。结构化证据记录保留确切首要文本和提示角色；本页未运行自然案例。

比较版本

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

claims · identity

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

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read executeDateTimeMethod together with the jsonpath context flags and RETURN_ERROR macro.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.jsonpath.datetime",
    "src.jsonpath.context-flags",
    "src.jsonpath.execute-context"
  ],
  "statement": "The fixed jsonpath datetime-method implementation first requires a string item. An explicit .datetime(template) call passes the template to parse_datetime with NULL ErrorSaveContext only when jspThrowErrors(cxt) is true; otherwise it saves the parse error and returns jperError. The no-template ISO candidate loop saves each candidate failure even on throwing execution, then the final RETURN_ERROR branch decides whether an unrecognized format throws 22031 or returns a path error. Lax controls structural auto-wrap/unwrap and structural errors; it does not generally suppress datetime parse/conversion errors. Precision, type conversion, and format guards remain 22031 paths."
}

claims · history

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

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.0",
    "primary_template": "%s format is not recognized: \"%s\"",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "22031"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "format is not recognized: \" \"",
      "position": 0,
      "role": "",
      "template": "%s format is not recognized: \"%s\""
    }
  ]
}

messages · message.string-only

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

messages · message.format-unrecognized

{
  "limits": "",
  "message_id": "message.format-unrecognized",
  "path": "",
  "position": 2,
  "raw": {
    "hint_template": "Use a datetime template argument to specify the input data format.",
    "id": "message.format-unrecognized",
    "primary_template": "%s format is not recognized: \"%s\"",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.datetime"
    ],
    "sqlstate": "22031"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.datetime"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "format is not recognized: \" \"",
      "position": 0,
      "role": "",
      "template": "%s format is not recognized: \"%s\""
    },
    {
      "kind": "hint",
      "literal": "Use a datetime template argument to specify the input data format.",
      "position": 1,
      "role": "",
      "template": "Use a datetime template argument to specify the input data format."
    }
  ]
}

messages · message.precision-range

{
  "limits": "",
  "message_id": "message.precision-range",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.precision-range",
    "primary_template": "time precision of jsonpath item method .%s() is out of range for type integer",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.datetime"
    ],
    "sqlstate": "22031"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.datetime"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "time precision of jsonpath item method . () is out of range for type integer",
      "position": 0,
      "role": "",
      "template": "time precision of jsonpath item method .%s() is out of range for type integer"
    }
  ]
}

messages · message.precision-invalid

{
  "limits": "",
  "message_id": "message.precision-invalid",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.precision-invalid",
    "primary_template": "time precision of jsonpath item method .%s() is invalid",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonpath.datetime"
    ],
    "sqlstate": "22031"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonpath.datetime"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "time precision of jsonpath item method . () is invalid",
      "position": 0,
      "role": "",
      "template": "time precision of jsonpath item method .%s() is invalid"
    }
  ]
}

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

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

sources · src.jsonpath.datetime

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

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:4e78c7f7e0b9ead98b7d55bf3db693d6f2993242e08b2438ca0a510f54a52de7

正文语言: zh-Hans · english-manuals:4e78c7f7e0b9ead98b7d55bf3db693d6f2993242e08b2438ca0a510f54a52de7