22031 invalid_argument_for_sql_json_datetime_function

速览

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

报文

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

含义

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

诊断

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

处理

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

版本

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

相关

22007、22018

来源

• 上游源码 src/backend/utils/errcodes.txt 第 216 行 REL_18_6 724edf9bd 6e8de346
• 上游源码 src/backend/utils/adt/jsonpath_exec.c 第 235 行 REL_18_6 724edf9bd 678cb894
• 上游源码 src/backend/utils/adt/jsonpath_exec.c 第 2326 行 REL_18_6 724edf9bd 678cb894
• 上游源码 src/backend/utils/adt/jsonpath_exec.c 第 654 行 REL_18_6 724edf9bd 678cb894
• 上游源码 src/backend/utils/adt/jsonpath_exec.c 第 2469 行 REL_18_6 724edf9bd 678cb894