Postgres Pro
Downloads
Home   >   mailing lists

Thread: Keyword docs missing, or mislabelled keywords

Keyword docs missing, or mislabelled keywords

From
PG Doc comments form
Date:
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/13/sql-keywords-appendix.html
Description:

https://www.postgresql.org/docs/13/sql-keywords-appendix.html

Missing:
BUFFERS (as found in EXPLAIN)
COSTS (as found in EXPLAIN)
MODULUS (as found in partition_bound_spec segment of ALTER TABLE)
REMAINDER (as found in partition_bound_spec segment of ALTER TABLE)
RESTRICTED (as found in CREATE FUNCTION (PARALLEL RESTRICTED))
SAFE (as found in CREATE FUNCTION (PARALLEL SAFE))
UNSAFE (as found in CREATE FUNCTION (PARALLEL UNSAFE))


Mislabelled:
FORMAT (is a keyword in EXPLAIN)

Re: Keyword docs missing, or mislabelled keywords

From
"David G. Johnston"
Date:
On Thu, Sep 2, 2021 at 7:11 AM PG Doc comments form <noreply@postgresql.org> wrote:

https://www.postgresql.org/docs/13/sql-keywords-appendix.html

Missing:

RESTRICTED (as found in CREATE FUNCTION (PARALLEL RESTRICTED))
SAFE (as found in CREATE FUNCTION (PARALLEL SAFE))
UNSAFE (as found in CREATE FUNCTION (PARALLEL UNSAFE))

I'll agree that the documentation for this doesn't fully describe the intricacies of the implementation, but the listing, at least for the PARALLEL related options, is correct.  Basically, our parser denotes PARALLEL as being an unreserved keyword, and because of this is able to identify the specific usage of PARALLEL {something} in CREATE FUNCTION and simply take "the next token" as a simple label (ColId) that gets passed along to the executor as state data.  Those labels thus do not need to be identified formally as keywords and thus are omitted from the table.

Per the cross-referenced 4.1 lead-in paragraph [1]:

"A token can be a key word, an identifier, a quoted identifier, a literal (or constant), or a special character symbol."

In terms of the above, RESTRICTED, SAFE, and UNSAFE are all "identifiers" [2].

We don't formally distinguish between "catalog recorded" identifiers and "simple label" identifiers - the perspective of the parser is that neither subclass has the limitations of a full keyword and neither requires any special knowledge or handling by the parser - the text can simply be passed along and the executor can be programmed to know which ones are which.

David J.

[1] https://www.postgresql.org/docs/13/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS

[2] https://github.com/postgres/postgres/blob/ba1b763102b89bca2711e921cf3083d8487b8c96/src/backend/parser/gram.y#L15414

Re: Keyword docs missing, or mislabelled keywords

From
Tom Lane
Date:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Thu, Sep 2, 2021 at 7:11 AM PG Doc comments form <noreply@postgresql.org>
> wrote:
>> Missing:
>> RESTRICTED (as found in CREATE FUNCTION (PARALLEL RESTRICTED))
>> SAFE (as found in CREATE FUNCTION (PARALLEL SAFE))
>> UNSAFE (as found in CREATE FUNCTION (PARALLEL UNSAFE))

> I'll agree that the documentation for this doesn't fully describe the
> intricacies of the implementation, but the listing, at least for the
> PARALLEL related options, is correct.

In recent versions that listing is guaranteed correct, because it's
generated mechanically from the same keyword list the grammar uses.

But, as you say, it's not the whole story because some commands have
options that are not keywords in the eyes of the grammar, just identifiers
that are looked up later.  Indeed we encourage that where we can, to avoid
grammar bloat.  Maybe it'd be appropriate to add some text here about
that?  But I'm not sure where to stop, because there are lots of things
that are identifiers but an unsophisticated user might think are keywords.
(Index type names, for example.)

            regards, tom lane