Ambiguity in VALUES synopsis: LIMIT vs FETCH - Mailing list pgsql-docs

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.

EnvironmentPostgreSQL v17.6

Best regards,
Cheng Ding
The University of Texas at Austin