public inbox for [email protected]help / color / mirror / Atom feed
Proposal for documenting 8.2 VALUES syntax 3+ messages / 2 participants [nested] [flat]
* Proposal for documenting 8.2 VALUES syntax @ 2006-09-15 21:14 Tom Lane <[email protected]> 2006-09-15 21:20 ` Re: Proposal for documenting 8.2 VALUES syntax Alvaro Herrera <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: Tom Lane @ 2006-09-15 21:14 UTC (permalink / raw) To: pgsql-docs; +Cc: Joe Conway <[email protected]> I spent a bit of time thinking about the best way to document 8.2's more powerful VALUES clause. Here's the plan I came up with: * There needs to be some introductory material in Part II, and the only place it seems to fit at all is under Chapter 7, Queries. I think there should be a new <sect1> page covering VALUES. We could add it at the end of the chapter (ie, a new section 7.7) or we could insert it between sections 7.3 Select Lists and 7.4 Combining Queries. The argument for the latter position is that VALUES is now syntactically parallel to SELECT, and so you can use it as if it were SELECT in UNION/INTERSECT/ EXCEPT structures as described in 7.4, as well as attach the ORDER BY, LIMIT, OFFSET clauses described in 7.5 and 7.6. However that might be putting too much emphasis on syntactic form as opposed to pedagogical clarity. I'm a bit inclined to put it at the end of the chapter and then explain "by the way, you can also attach that other stuff to it". Thoughts? * The SELECT reference page is huge already, so I would rather add only the minimum possible amount to it. This leads to the conclusion that we'd better create a new ref/ entry just for VALUES. I think that's appropriate anyway, since there is some material that doesn't seem like it would fit anywhere else --- in particular, that we want to warn off people from expecting umpteen-billion-row VALUES constructs to work well. * Joe's original draft docs patch added examples to the INSERT, UPDATE, DELETE, etc reference pages. While we obviously have got to update the INSERT page, I'm inclined to use the rest of that material in the new VALUES reference page. Comments? regards, tom lane ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Proposal for documenting 8.2 VALUES syntax 2006-09-15 21:14 Proposal for documenting 8.2 VALUES syntax Tom Lane <[email protected]> @ 2006-09-15 21:20 ` Alvaro Herrera <[email protected]> 2006-09-15 21:49 ` Re: Proposal for documenting 8.2 VALUES syntax Tom Lane <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: Alvaro Herrera @ 2006-09-15 21:20 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs; Joe Conway <[email protected]> Tom Lane wrote: > I spent a bit of time thinking about the best way to document 8.2's more > powerful VALUES clause. Here's the plan I came up with: > > * There needs to be some introductory material in Part II, and the only > place it seems to fit at all is under Chapter 7, Queries. I think there > should be a new <sect1> page covering VALUES. We could add it at the > end of the chapter (ie, a new section 7.7) or we could insert it between > sections 7.3 Select Lists and 7.4 Combining Queries. The argument for > the latter position is that VALUES is now syntactically parallel to > SELECT, and so you can use it as if it were SELECT in UNION/INTERSECT/ > EXCEPT structures as described in 7.4, as well as attach the ORDER BY, > LIMIT, OFFSET clauses described in 7.5 and 7.6. However that might be > putting too much emphasis on syntactic form as opposed to pedagogical > clarity. I'm a bit inclined to put it at the end of the chapter and > then explain "by the way, you can also attach that other stuff to it". > Thoughts? I agree with putting it at the end of the chapter. > * The SELECT reference page is huge already, so I would rather add only > the minimum possible amount to it. This leads to the conclusion that > we'd better create a new ref/ entry just for VALUES. I think that's > appropriate anyway, since there is some material that doesn't seem like > it would fit anywhere else --- in particular, that we want to warn off > people from expecting umpteen-billion-row VALUES constructs to work > well. I agree here as well. One likely useful example, if not already covered, is select ... FROM ... WHERE op ANY (VALUES ( ... )) I tripped over it a couple of days ago and it seems useful and non obvious. ISTM it beats the current practice of op ANY(ARRAY[ ... ]) which seems a bit of a kludge. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Proposal for documenting 8.2 VALUES syntax 2006-09-15 21:14 Proposal for documenting 8.2 VALUES syntax Tom Lane <[email protected]> 2006-09-15 21:20 ` Re: Proposal for documenting 8.2 VALUES syntax Alvaro Herrera <[email protected]> @ 2006-09-15 21:49 ` Tom Lane <[email protected]> 0 siblings, 0 replies; 3+ messages in thread From: Tom Lane @ 2006-09-15 21:49 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: pgsql-docs; Joe Conway <[email protected]> Alvaro Herrera <[email protected]> writes: > ... One likely useful example, if not already covered, is > select ... FROM ... WHERE op ANY (VALUES ( ... )) > I tripped over it a couple of days ago and it seems useful and non > obvious. ISTM it beats the current practice of > op ANY(ARRAY[ ... ]) > which seems a bit of a kludge. Unfortunately, we don't optimize the former nearly as well as the latter :-(. I was thinking of showing an example of a multi-column IN: where (firstname,lastname) in (values ('joe','blow'), ('anne','smith'), ... but I don't think we want to encourage people to use it in cases where a scalar list or ANY(ARRAY) will serve. Maybe next year ;-) regards, tom lane ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2006-09-15 21:49 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2006-09-15 21:14 Proposal for documenting 8.2 VALUES syntax Tom Lane <[email protected]> 2006-09-15 21:20 ` Alvaro Herrera <[email protected]> 2006-09-15 21:49 ` Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox