Hi,
The attached documentation patch, doc-subqueries-v1.patch,
applies against head.
I wanted to document that subqueries can't modify data.
This is mentioned in the documentation for SELECT and
implied elsewhere but I was looking for something more
than an 'in-passing' mention.
(I wrote a bad query,
modifying data in a subquery, couldn't recall where
it was documented that you can't do this, and couldn't
find the answer from the TOC or the index. Now that
there's lots of statements with RETURNING clauses
it's natural to want to use them in subqueries.)
There seemed to be no good place to put this in the
tutorial section of the documentation. I wound
up adding a small, 2 paragraph, section describing subqueries to
the chapter on queries. Although the first paragraph
echos what's already documented the utility of
subqueries is such that it's nice to have a
place in the tutorial that serves as a single point of
reference.
The alternative seemed to be to put the 2nd paragraph
in "9.22. Subquery Expressions", and this didn't seem
to fit well.
The last 2 sentences of the first paragraph are
something in the way of helpful hints and may not
be appropriate, or even accurate. I've left them in
for review.
Regards,
Karl <k...@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index d7b0d73..acc6686 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -549,7 +549,7 @@ SELECT * FROM my_table AS m WHERE my_table.a > 5; -- wrong
SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id;
</programlisting>
Additionally, an alias is required if the table reference is a
- subquery (see <xref linkend="queries-subqueries">).
+ subquery (see <xref linkend="queries-subquery-derived-tables">).
</para>
<para>
@@ -590,10 +590,10 @@ SELECT a.* FROM (my_table AS a JOIN your_table AS b ON ...) AS c
</para>
</sect3>
- <sect3 id="queries-subqueries">
- <title>Subqueries</title>
+ <sect3 id="queries-subquery-derived-tables">
+ <title>Subquery Derived Tables</title>
- <indexterm zone="queries-subqueries">
+ <indexterm zone="queries-subquery-derived-tables">
<primary>subquery</primary>
</indexterm>
@@ -1315,6 +1315,46 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
</sect1>
+ <sect1 id="queries-subqueries">
+ <title>Subqueries</title>
+
+ <indexterm zone="queries-subqueries">
+ <primary>subquery</primary>
+ </indexterm>
+
+ <indexterm zone="queries-subqueries">
+ <primary>sub-select</primary>
+ </indexterm>
+
+ <para>
+ Subqueries, also called sub-selects, are queries written within
+ parenthesis in the text of larger queries. The values produced by
+ subqueries may be scalar, used within expressions as described
+ in <xref linkend="sql-syntax-scalar-subqueries">, or tabular. When
+ tabular, subqueries may substitute for tables, as described
+ in <xref linkend="queries-subquery-derived-tables">, generate array
+ content, as described
+ in <xref linkend="sql-syntax-array-constructors">, have their
+ result content tested within expressions, as described
+ in <xref linkend="functions-subquery">, or be used in other
+ contexts. Often either joins or subqueries can be used to produce
+ different query plans yielding identical output. Which technique
+ is appropriate depends upon circumstance but it is worth noting
+ that more work has gone into query planner join optimization.
+ </para>
+
+ <para>
+ Subqueries may not modify database
+ content. <link linkend="queries-with">Common Table
+ Expressions</link> are one way to integrate data returned by data
+ modification statements,
+ i.e. <command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command>
+ statements with <literal>RETURNING</literal> clauses, into larger
+ queries.
+ </para>
+ </sect1>
+
+
<sect1 id="queries-union">
<title>Combining Queries</title>
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
