Allow WITH clauses to be attached to INSERT, UPDATE, DELETE statements.

[postgresql] / doc / src / sgml / ref / insert.sgml

diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 98a1ca28b7923e0452b79a4c49c3423b5bffe764..629cc7ea558426781314b3b25b7dad8b84659bb1 100644 (file)
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -1,11 +1,11 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.37 2008/11/14 10:22:47 petere Exp $
+doc/src/sgml/ref/insert.sgml
 PostgreSQL documentation
 -->
 
 <refentry id="SQL-INSERT">
  <refmeta>
-  <refentrytitle id="SQL-INSERT-TITLE">INSERT</refentrytitle>
+  <refentrytitle>INSERT</refentrytitle>
   <manvolnum>7</manvolnum>
   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  </refmeta>
@@ -21,6 +21,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
+[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
 INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
     { DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) [, ...] | <replaceable class="PARAMETER">query</replaceable> }
     [ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
@@ -69,11 +70,14 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
 
   <para>
    You must have <literal>INSERT</literal> privilege on a table in
-   order to insert into it, and <literal>SELECT</> privilege on it to
-   use <literal>RETURNING</>.  If you use the <replaceable
+   order to insert into it.  If a column list is specified, you only
+   need <literal>INSERT</literal> privilege on the listed columns.
+   Use of the <literal>RETURNING</> clause requires <literal>SELECT</>
+   privilege on all columns mentioned in <literal>RETURNING</>.
+   If you use the <replaceable
    class="PARAMETER">query</replaceable> clause to insert rows from a
-   query, you also need to have <literal>SELECT</literal> privilege on
-   any table used in the query.
+   query, you of course need to have <literal>SELECT</literal> privilege on
+   any table or column used in the query.
   </para>
  </refsect1>
 
@@ -81,6 +85,26 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
   <title>Parameters</title>
 
   <variablelist>
+   <varlistentry>
+    <term><replaceable class="parameter">with_query</replaceable></term>
+    <listitem>
+     <para>
+      The <literal>WITH</literal> clause allows you to specify one or more
+      subqueries that can be referenced by name in the <command>INSERT</>
+      query. See <xref linkend="queries-with"> and <xref linkend="sql-select">
+      for details.
+     </para>
+     <para>
+      It is possible for the <replaceable class="parameter">query</replaceable>
+      (<command>SELECT</command> statement)
+      to also contain a <literal>WITH</literal> clause.  In such a case both
+      sets of <replaceable>with_query</replaceable> can be referenced within
+      the <replaceable class="parameter">query</replaceable>, but the
+      second one takes precedence since it is more closely nested.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><replaceable class="PARAMETER">table</replaceable></term>
     <listitem>
@@ -137,7 +161,7 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
      <para>
       A query (<command>SELECT</command> statement) that supplies the
       rows to be inserted.  Refer to the
-      <xref linkend="sql-select" endterm="sql-select-title">
+      <xref linkend="sql-select">
       statement for a description of the syntax.
      </para>
     </listitem>
@@ -284,7 +308,9 @@ INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   <para>
    <command>INSERT</command> conforms to the SQL standard, except that
    the <literal>RETURNING</> clause is a
-   <productname>PostgreSQL</productname> extension.  Also, the case in
+   <productname>PostgreSQL</productname> extension, as is the ability
+   to use <literal>WITH</> with <command>INSERT</>.
+   Also, the case in
    which a column name list is omitted, but not all the columns are
    filled from the <literal>VALUES</> clause or <replaceable>query</>,
    is disallowed by the standard.
@@ -293,7 +319,7 @@ INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   <para>
    Possible limitations of the <replaceable
    class="PARAMETER">query</replaceable> clause are documented under
-   <xref linkend="sql-select" endterm="sql-select-title">.
+   <xref linkend="sql-select">.
   </para>
  </refsect1>
 </refentry>