Hello docs team,
I believe there’s an ambiguity in the VALUES command synopsis that can
mislead readers into thinking LIMIT and FETCH can be used together.
*What I ran*
VALUES (12, 'nectarine') LIMIT 1 FETCH FIRST 1 ROW ONLY;
*What happened*
ERROR: syntax error at or near "FETCH"
*Why I think the docs are ambiguous*
The current synopsis for VALUES shows:
VALUES ( expression [, ...] ) [, ...][ ORDER BY sort_expression [ ASC
| DESC | USING operator ] [, ...] ][ LIMIT { count | ALL } ][ OFFSET
start [ ROW | ROWS ] ][ FETCH { FIRST | NEXT } [ count ] { ROW | ROWS
} ONLY ]
As written, this looks like LIMIT … and FETCH … are independent optional
clauses that could both appear. In practice (and in the underlying
grammar), FETCH is the SQL-standard alternative to LIMIT; they are mutually
exclusive.
*Suggested fix (one option)*
Adjust the synopsis to make the alternation explicit, for example:
[ { LIMIT { count | ALL } [ OFFSET start [ ROW | ROWS ] ]
| [ OFFSET start [ ROW | ROWS ] ] FETCH { FIRST | NEXT } [ count ] {
ROW | ROWS } ONLY } ]
Alternatively, add a short note right under the synopsis:
Note: FETCH { FIRST | NEXT } … ONLY is an alternative to LIMIT and cannot
be used together with it.
*Environment*
PostgreSQL v17.6
Best regards,
Cheng Ding
The University of Texas at Austin
