2202H — invalid_tablesample_argument
2202H
速览
TABLESAMPLE 方法收到无效参数。固定核心和 contrib 方法会以方法专属报文拒绝越界百分比或负样本数量。
| 字段 | 值 |
|---|---|
| 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 |
| 别名 | — |
报文
固定执行器和采样方法使用以下首要文本：
| 归属/守卫 | 首要文本 |
|---|---|
| 方法参数为 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 |
含义
2202H 是方法参数代码，不是一个适用于所有 TABLESAMPLE 的统一范围。执行器在调用方法前拒绝 NULL 方法参数。核心 Bernoulli 和 system 方法接受包含端点的 0 到 100 百分比，并拒绝 NaN。system_rows contrib 方法只拒绝负的请求行数，因此零是允许的；system_time 拒绝负值或 NaN 的采样时间，因此零是允许的；该 guard 没有设置有限的上界，正 Infinity 不会被这个比较本身拒绝。REPEATABLE NULL 属于独立的 2202G 分支，其他采样扩展也可能有自己的参数守卫。
诊断
先定位采样方法和参数位置，再修改值。方法参数为 NULL 指向执行器守卫；0 到 100 之外或 NaN 的 Bernoulli/system 百分比指向核心方法；负的 system_rows 数量以及负或 NaN 的 system_time 属于 contrib 方法；该 guard 本身不会把正 Infinity 分类为错误。结合首要报文区分这些情况和 NULL REPEATABLE seed（2202G）。
处理
按所选方法使用非 NULL 参数、包含端点的有限 0 到 100 百分比、非负行数或通过其负值/NaN guard 的 system_time 值。不要通过修改方法百分比来修复 2202G 的重复 seed 错误。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的语句。
版本
锁定目录从 9.5.0 起记录该条件；本页固定核心及 contrib 源码路径为 PostgreSQL 18.6。未声称本页有自然运行观察。
相关
来源
执行器 NULL 守卫见 src/backend/executor/nodeSamplescan.c#L232-245。核心百分比守卫见 src/backend/access/tablesample/bernoulli.c#L137-149 和 src/backend/access/tablesample/system.c#L140-152。contrib 范围见 contrib/tsm_system_rows/tsm_system_rows.c#L178-187 和 contrib/tsm_system_time/tsm_system_time.c#L193-203。结构化证据记录保留方法专属报文和范围；本页未运行自然案例。