↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 错误代码 / Class 22 数据异常

22031 invalid_argument_for_sql_json_datetime_function

ERROR 源码确认 参考 未实测

类别
Class 22 数据异常
严重等级
ERROR
条件名
invalid_argument_for_sql_json_datetime_function
宏名称
ERRCODE_INVALID_ARGUMENT_FOR_SQL_JSON_DATETIME_FUNCTION
启用版本
13
状态
活跃

版本覆盖

  1. 18
  2. 17
  3. 16
  4. 15
  5. 14
  1. 13
  2. 12
  3. 11
  4. 10
  1. 19 beta
  2. 20 dev

速览

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

报文

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

守卫 首要文本和提示
输入项不是字符串 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

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 %s format is not recognized: "%s"

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

主消息 jsonpath item method .%s() can only be applied to a string

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

主消息 %s format is not recognized: "%s"
HINT Use a datetime template argument to specify the input data format.

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

主消息 time precision of jsonpath item method .%s() is out of range for type integer

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

主消息 time precision of jsonpath item method .%s() is invalid

来源：src/backend/utils/adt/jsonpath_exec.c @ REL_18_6

含义

固定的 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。未声称本页有自然运行观察。

来源

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

  • 22031 is invalid_argument_for_sql_json_datetime_function in SQLSTATE Class 22.

    核实方式Read fixed definition.

    来源src/backend/utils/errcodes.txt

  • 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.

    核实方式Read executeDateTimeMethod together with the jsonpath context flags and RETURN_ERROR macro.

    不覆盖Source confirmation is not a natural runtime observation.

    来源src/backend/utils/adt/jsonpath_exec.c · src/backend/utils/adt/jsonpath_exec.c · src/backend/utils/adt/jsonpath_exec.c · src/backend/utils/adt/jsonpath_exec.c

  • The locked catalogue records 22031 from 13.0 without proving exact implementation introduction.

    核实方式Use catalogue boundary.

    来源src/backend/utils/errcodes.txt

同类错误代码

Class 22 数据异常 下的其他成员。