# 2202H — invalid_tablesample_argument

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

# 2202H

## 速览 {#at-a-glance}
TABLESAMPLE 方法收到无效参数。固定核心和 contrib 方法会以方法专属报文拒绝越界百分比或负样本数量。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `2202H` |
| 条件名 | `invalid_tablesample_argument` |
| 状态 | `有效` |
| 已知存在于 | `9.5.0` |
| 锁定快照 | `9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_INVALID_TABLESAMPLE_ARGUMENT` |
| 别名 | `—` |

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

## 报文 {#messages}
固定执行器和采样方法使用以下首要文本：

| 归属/守卫 | 首要文本 |
| --- | --- |
| 方法参数为 NULL | `TABLESAMPLE parameter cannot be null` |
| Bernoulli/system 百分比（包括 NaN） | `sample percentage must be between 0 and 100` |
| `system_rows` 数量为负 | `sample size must not be negative` |
| `system_time` 时间为负或 NaN | `sample collection time must not be negative` |

## 含义 {#meaning}
2202H 是方法参数代码，不是一个适用于所有 TABLESAMPLE 的统一范围。执行器在调用方法前拒绝 NULL 方法参数。核心 Bernoulli 和 system 方法接受包含端点的 0 到 100 百分比，并拒绝 NaN。`system_rows` contrib 方法只拒绝负的请求行数，因此零是允许的；`system_time` 拒绝负值或 NaN 的采样时间，因此零是允许的；该 guard 没有设置有限的上界，正 Infinity 不会被这个比较本身拒绝。`REPEATABLE NULL` 属于独立的 2202G 分支，其他采样扩展也可能有自己的参数守卫。

## 诊断 {#diagnosis}
先定位采样方法和参数位置，再修改值。方法参数为 NULL 指向执行器守卫；0 到 100 之外或 NaN 的 Bernoulli/system 百分比指向核心方法；负的 `system_rows` 数量以及负或 NaN 的 `system_time` 属于 contrib 方法；该 guard 本身不会把正 Infinity 分类为错误。结合首要报文区分这些情况和 NULL REPEATABLE seed（2202G）。

## 处理 {#response}
按所选方法使用非 NULL 参数、包含端点的有限 0 到 100 百分比、非负行数或通过其负值/NaN guard 的 `system_time` 值。不要通过修改方法百分比来修复 2202G 的重复 seed 错误。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的语句。

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

## 相关 {#related}
[`2202G`](../2202g/)、[`22023`](../22023/)

## 来源 {#sources}
执行器 NULL 守卫见 [`src/backend/executor/nodeSamplescan.c#L232-245`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/executor/nodeSamplescan.c#L232)。核心百分比守卫见 [`src/backend/access/tablesample/bernoulli.c#L137-149`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/tablesample/bernoulli.c#L137) 和 [`src/backend/access/tablesample/system.c#L140-152`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/tablesample/system.c#L140)。contrib 范围见 [`contrib/tsm_system_rows/tsm_system_rows.c#L178-187`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/tsm_system_rows/tsm_system_rows.c#L178) 和 [`contrib/tsm_system_time/tsm_system_time.c#L193-203`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/tsm_system_time/tsm_system_time.c#L193)。结构化[证据记录](../../data/evidence/2202h.json)保留方法专属报文和范围；本页未运行自然案例。