# 22033 — invalid_sql_json_subscript

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

# 22033

## 速览 {#at-a-glance}
SQL/JSON 数组下标无效。固定 jsonpath 路径区分越界、非单一数值和整数范围变体。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22033` |
| 条件名 | `invalid_sql_json_subscript` |
| 状态 | `有效` |
| 已知存在于 | `12.0` |
| 锁定快照 | `12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_INVALID_SQL_JSON_SUBSCRIPT` |
| 别名 | `—` |

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

## 报文 {#messages}
固定下标守卫使用以下首要文本：

| 守卫 | 首要文本 |
| --- | --- |
| 下标不是单个数值项 | `jsonpath array subscript is not a single numeric value` |
| 数值下标超出 int32 | `jsonpath array subscript is out of integer range` |
| strict 数组边界失败 | `jsonpath array subscript is out of bounds` |

## 含义 {#meaning}
jsonpath 执行器把每个下标表达式求值为结果列表。`getArrayIndex` 要求结果恰好是一个数值标量，将其截断为整数；结果不是单个数值项或无法符合整数范围时报告 22033。随后数组边界守卫在 strict 模式下对负起点、反向范围或超过数组上界的终点报告同一码。lax 模式会忽略这种结构性越界错误，并把范围限制到现有数组；它不会把非数值或溢出的下标变成有效下标。

## 诊断 {#diagnosis}
先检查下标表达式的基数和类型，再检查数组长度。表达式返回多个项、非数值或整数溢出时使用转换报文；数值下标或范围违反 strict 数组边界时使用越界报文。记录 path 是 strict 还是 lax，因为 lax 的结构处理可能产生空结果或被限制的结果，而不是 ERROR。后续 SQL/JSON 操作若选择对无项抛错，则属于 22035。

## 处理 {#response}
使下标表达式返回整数范围内的单个有限数值，并在 strict 模式下保持目标数组边界内且范围不反向。如果有意使用 lax 的限制或空结果，应确认 path 模式和外层 SQL/JSON 行为确实表达了该意图。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的表达式。

## 版本 {#versions}
锁定目录从 12.0 起记录该条件；本页固定 jsonpath 源码路径为 PostgreSQL 18.6。未声称本页有自然运行观察。

## 相关 {#related}
[`22034`](../22034/)、[`22035`](../22035/)

## 来源 {#sources}
数组边界处理见 [`src/backend/utils/adt/jsonpath_exec.c#L892-929`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L892)。下标基数、截断和整数转换见 [`#L3442-3477`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L3442)。结构化[证据记录](../../data/evidence/22033.json)保留三个 22033 守卫角色；本页未运行自然案例。