diff options
Diffstat (limited to 'doc/src/sgml/ref/update.sgml')
| -rw-r--r-- | doc/src/sgml/ref/update.sgml | 57 |
1 files changed, 54 insertions, 3 deletions
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 3b03e86a1e..5d1265e945 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.37 2006/03/08 22:59:09 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.38 2006/08/12 02:52:03 tgl Exp $ PostgreSQL documentation --> @@ -24,6 +24,7 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep SET <replaceable class="PARAMETER">column</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] [ FROM <replaceable class="PARAMETER">fromlist</replaceable> ] [ WHERE <replaceable class="PARAMETER">condition</replaceable> ] + [ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ AS <replaceable class="parameter">output_name</replaceable> ] [, ...] ] </synopsis> </refsynopsisdiv> @@ -53,6 +54,16 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep </para> <para> + The optional <literal>RETURNING</> clause causes <command>UPDATE</> + to compute and return value(s) based on each row actually updated. + Any expression using the table's columns, and/or columns of other + tables mentioned in <literal>FROM</literal>, can be computed. + The new (post-update) values of the table's columns are used. + The syntax of the <literal>RETURNING</> list is identical to that of the + output list of <command>SELECT</>. + </para> + + <para> You must have the <literal>UPDATE</literal> privilege on the table to update it, as well as the <literal>SELECT</literal> privilege to any table whose values are read in the @@ -147,6 +158,28 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep </para> </listitem> </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">output_expression</replaceable></term> + <listitem> + <para> + An expression to be computed and returned by the <command>UPDATE</> + command after each row is updated. The expression may use any + column names of the <replaceable class="PARAMETER">table</replaceable> + or table(s) listed in <literal>FROM</>. + Write <literal>*</> to return all columns. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">output_name</replaceable></term> + <listitem> + <para> + A name to use for a returned column. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -165,6 +198,14 @@ UPDATE <replaceable class="parameter">count</replaceable> class="parameter">condition</replaceable> (this is not considered an error). </para> + + <para> + If the <command>UPDATE</> command contains a <literal>RETURNING</> + clause, the result will be similar to that of a <command>SELECT</> + statement containing the columns and values defined in the + <literal>RETURNING</> list, computed over the row(s) updated by the + command. + </para> </refsect1> <refsect1> @@ -213,6 +254,16 @@ UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT </para> <para> + Perform the same operation and return the updated entries: + +<programlisting> +UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT + WHERE city = 'San Francisco' AND date = '2003-07-03' + RETURNING temp_lo, temp_hi, prcp; +</programlisting> + </para> + + <para> Increment the sales count of the salesperson who manages the account for Acme Corporation, using the <literal>FROM</literal> clause syntax: @@ -256,8 +307,8 @@ COMMIT; <para> This command conforms to the <acronym>SQL</acronym> standard, except - that the <literal>FROM</literal> clause is a - <productname>PostgreSQL</productname> extension. + that the <literal>FROM</literal> and <literal>RETURNING</> clauses + are <productname>PostgreSQL</productname> extensions. </para> <para> |