2202H
Read PG 18 manual ↗invalid_tablesample_argument
- SQLSTATE
- 2202H
- Condition name
- invalid_tablesample_argument
- Class
- Data Exception
- Source macro
- ERRCODE_INVALID_TABLESAMPLE_ARGUMENT
- Evidence
- Source path confirmed
English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗
At a glance
A TABLESAMPLE method received an invalid argument. Fixed core and contrib methods reject out-of-range percentages or negative sample sizes with method-specific messages.
Messages
The fixed executor and sampling methods use these primary texts:
| Owner / guard | Primary |
|---|---|
| NULL method argument | TABLESAMPLE parameter cannot be null |
| Bernoulli/system percentage, including NaN | sample percentage must be between 0 and 100 |
system_rows negative size |
sample size must not be negative |
system_time negative or NaN time |
sample collection time must not be negative |
Meaning
2202H is a method-argument code, not one universal TABLESAMPLE range. The executor rejects a NULL method argument before calling the method. Core Bernoulli and system methods accept percentages from 0 through 100 inclusive and reject NaN. The system_rows contrib method rejects only a negative requested row count, so zero is allowed; system_time rejects negative or NaN collection time, so zero is allowed; the shown guard does not impose a finite upper bound, and positive Infinity is not rejected by that comparison itself. REPEATABLE NULL is the separate 2202G branch, and other sampling extensions may define their own argument guards.
Diagnosis
Identify the sampling method and parameter position before changing the value. A NULL method argument points to the executor guard; a Bernoulli/system percentage outside 0..100 or NaN points to the core method; negative system_rows size and negative/NaN system_time are contrib-specific; positive Infinity is not classified by that shown guard. Read the primary text to distinguish these from a NULL REPEATABLE seed (2202G).
Response
Use a non-NULL method argument, a finite percentage in the inclusive 0..100 range, a non-negative row count, or a non-negative finite collection time according to the selected method. Do not repair a 2202G repeat-seed error by changing the method percentage. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected statement.
Versions
The locked catalogue records this condition from 9.5.0; the fixed core and contrib source paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.
Sources
The executor NULL guard is src/backend/executor/nodeSamplescan.c#L232-245. Core percentage guards are src/backend/access/tablesample/bernoulli.c#L137-149 and src/backend/access/tablesample/system.c#L140-152. Contrib bounds are contrib/tsm_system_rows/tsm_system_rows.c#L178-187 and contrib/tsm_system_time/tsm_system_time.c#L193-203. The structured evidence record retains the method-specific messages and limits; no natural runtime was run.
Source evidence
Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.
2202H is invalid_tablesample_argument in SQLSTATE Class 22.
Method: Read fixed definition.
Fixed core and contrib TABLESAMPLE methods share 2202H for method-argument validation: Bernoulli/system reject percentages outside 0..100 and NaN, the executor rejects a NULL method parameter, system_rows rejects negative size, and system_time rejects negative or NaN collection time. The shown system_time guard does not impose a finite upper bound, so positive Infinity is not rejected by that comparison itself.
Method: Read the executor parameter loop and complete core/contrib BeginSampleScan guards.
Limits: Source confirmation is not a natural runtime observation.
src.path.0 src.nodeSamplescan.argument src.system.tablesample src.system_rows.tablesample src.system_time.tablesample
The locked catalogue records 2202H from 9.5.0 without proving exact implementation introduction.
Method: Use catalogue boundary.
- src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/access/tablesample/bernoulli.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/executor/nodeSamplescan.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/access/tablesample/system.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - contrib/tsm_system_rows/tsm_system_rows.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - contrib/tsm_system_time/tsm_system_time.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
Message templates
ERROR · message.0
Primary
sample percentage must be between 0 and 100
ERROR · message.parameter-null
Primary
TABLESAMPLE parameter cannot be null
ERROR · message.sample-percentage
Primary
sample percentage must be between 0 and 100
ERROR · message.sample-size
Primary
sample size must not be negative
ERROR · message.sample-time
Primary
sample collection time must not be negative
Reproduction & repair cases
No reproduction case is attached to this condition.
Recorded runtime evidence
No runtime observation is attached to this entry.
Version history 1
- PG 9.4 → 9.5added
Definition snapshot: english-manuals:e162b067d9ca56bc59fa37a7d58… · English manual source