Обсуждение: Proposal for documenting 8.2 VALUES syntax

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

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

Alvaro Herrera <alvherre@commandprompt.com> 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