Thread: BUG #13966: Documentation. 'Select' description
The following bug has been logged on the website: Bug reference: 13966 Logged by: Iurii Popov Email address: iurii.i.popov@gmail.com PostgreSQL version: 9.5.1 Operating system: Ubuntu Description: There is the description mismatch at documentation. 1. http://www.postgresql.org/docs/9.5/static/sql-select.html (SELECT) Each subquery can be a SELECT, TABLE, VALUES, INSERT, UPDATE or DELETE statement. 2. http://www.postgresql.org/docs/9.5/static/queries-with.html (7.8. WITH Queries (Common Table Expressions)) Each auxiliary statement in a WITH clause can be a SELECT, INSERT, UPDATE, or DELETE; Where is TABLE and VALUES?
On Wed, Feb 17, 2016 at 8:03 AM, <iurii.i.popov@gmail.com> wrote: > The following bug has been logged on the website: > > Bug reference: 13966 > Logged by: Iurii Popov > Email address: iurii.i.popov@gmail.com > PostgreSQL version: 9.5.1 > Operating system: Ubuntu > Description: > > There is the description mismatch at documentation. > > 1. http://www.postgresql.org/docs/9.5/static/sql-select.html (SELECT) > > Each subquery can be a SELECT, TABLE, VALUES, INSERT, UPDATE or DELETE > statement. > > 2. http://www.postgresql.org/docs/9.5/static/queries-with.html (7.8. WITH > Queries (Common Table Expressions)) > > Each auxiliary statement in a WITH clause can be a SELECT, INSERT, UPDATE= , > or DELETE; > > Where is TABLE and VALUES? =E2=80=8BWhile being thorough is admirable the SELECT documentation you ref= erence is official (and thus complete) =E2=80=8Bcommand reference. The WITH secti= on referenced is more descriptive in nature and doesn't have to specify/repeat knowledge provided elsewhere. In the particular case the previous section discusses "VALUES" and says that VALUES can be used in any place that SELECT can be used. Thus, while reading the WITH section and seeing SELECT the documentation is allowed to assume that the reader has the knowledge that VALUES could replace SELECT in this situation. Likewise, the only place TABLE is documented is within the context of SELECT and there it is spelled out where one is allowed to use TABLE. Stating the same here would be repeating information defined elsewhere. While that may be desirable the use of TABLE is so uncommon that it inclusion in this section would, IMO, just introduce the reader to a concept that they have not previously seen nor likely need to be aware of in order to understand how WITH/CTEs work. So, I would say the level of detail given in the CTE/WITH section is just right. Adding more for the sake of being precise just takes away from the main goal which is to familiarize the reader with how this clause works. David J.
David G. Johnston wrote: > On Wed, Feb 17, 2016 at 8:03 AM, <iurii.i.popov@gmail.com> wrote: > > There is the description mismatch at documentation. > > > > 1. http://www.postgresql.org/docs/9.5/static/sql-select.html (SELECT) > > > > Each subquery can be a SELECT, TABLE, VALUES, INSERT, UPDATE or DELETE > > statement. > > > > 2. http://www.postgresql.org/docs/9.5/static/queries-with.html (7.8. WITH > > Queries (Common Table Expressions)) > > > > Each auxiliary statement in a WITH clause can be a SELECT, INSERT, UPDATE, > > or DELETE; > > > > Where is TABLE and VALUES? > > > While being thorough is admirable the SELECT documentation you reference > is official (and thus complete) command reference. The WITH section > referenced is more descriptive in nature and doesn't have to specify/repeat > knowledge provided elsewhere. I'm not sure I agree with your rationale. Listing some keywords but not all seems confusing -- it's easy to get the impression that the list is exhaustive. I wonder if we can say something like "any of the SELECT variants", instead of just SELECT. On the other hand, WITH itself is sometimes seen as one of the SELECT variants (in fact if you do "man WITH" you get the SELECT page, just like you do if you do "man TABLE" -- though curiously enough "man VALUES" is a different page), so that might misled people into thinking that you can put one WITH clause inside another. It seems easier to just add TABLE and VALUES to the list. BTW I think we should add generate_series() to the SEE ALSO section of the VALUES manpage. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services