# 22031 — invalid_argument_for_sql_json_datetime_function

> PostgreSQL SQLSTATE 22031 的来源与诊断参考。
---

# 22031

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

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22031` |
| 条件名 | `invalid_argument_for_sql_json_datetime_function` |
| 状态 | `有效` |
| 已知存在于 | `13.0` |
| 锁定快照 | `13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_INVALID_ARGUMENT_FOR_SQL_JSON_DATETIME_FUNCTION` |
| 别名 | `—` |

<!-- source facts: data/errcodes/22031.json -->
<!-- END SQLSTATE FACTS -->

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

## 相关 {#related}
[`22007`](../22007/)、[`22018`](../22018/)

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