Adding upstream version 15.4.upstream/15.4 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-16 19:46:48 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-16 19:46:48 +0000
commit: 311bcfc6b3acdd6fd152798c7f287ddf74fa2a98 (patch)
tree: 0ec307299b1dada3701e42f4ca6eda57d708261e /doc/src/sgml/html/sql-update.html
parent: Initial commit. (diff)
download: postgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.tar.xz
postgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.zip
1 files changed, 290 insertions, 0 deletions
diff --git a/doc/src/sgml/html/sql-update.html b/doc/src/sgml/html/sql-update.html
new file mode 100644
index 0000000..a980363
--- /dev/null
+++ b/doc/src/sgml/html/sql-update.html
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>UPDATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-unlisten.html" title="UNLISTEN" /><link rel="next" href="sql-vacuum.html" title="VACUUM" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">UPDATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-unlisten.html" title="UNLISTEN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-vacuum.html" title="VACUUM">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-UPDATE"><div class="titlepage"></div><a id="id-1.9.3.183.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">UPDATE</span></h2><p>UPDATE — update rows of a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+UPDATE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ [ AS ] <em class="replaceable"><code>alias</code></em> ]
+    SET { <em class="replaceable"><code>column_name</code></em> = { <em class="replaceable"><code>expression</code></em> | DEFAULT } |
+          ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = [ ROW ] ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) |
+          ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = ( <em class="replaceable"><code>sub-SELECT</code></em> )
+        } [, ...]
+    [ FROM <em class="replaceable"><code>from_item</code></em> [, ...] ]
+    [ WHERE <em class="replaceable"><code>condition</code></em> | WHERE CURRENT OF <em class="replaceable"><code>cursor_name</code></em> ]
+    [ RETURNING * | <em class="replaceable"><code>output_expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]
+</pre></div><div class="refsect1" id="id-1.9.3.183.5"><h2>Description</h2><p>
+   <code class="command">UPDATE</code> changes the values of the specified
+   columns in all rows that satisfy the condition. Only the columns to
+   be modified need be mentioned in the <code class="literal">SET</code> clause;
+   columns not explicitly modified retain their previous values.
+  </p><p>
+   There are two ways to modify a table using information contained in
+   other tables in the database: using sub-selects, or specifying
+   additional tables in the <code class="literal">FROM</code> clause. Which
+   technique is more appropriate depends on the specific
+   circumstances.
+  </p><p>
+   The optional <code class="literal">RETURNING</code> clause causes <code class="command">UPDATE</code>
+   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 <code class="literal">FROM</code>, can be computed.
+   The new (post-update) values of the table's columns are used.
+   The syntax of the <code class="literal">RETURNING</code> list is identical to that of the
+   output list of <code class="command">SELECT</code>.
+  </p><p>
+   You must have the <code class="literal">UPDATE</code> privilege on the table,
+   or at least on the column(s) that are listed to be updated.
+   You must also have the <code class="literal">SELECT</code>
+   privilege on any column whose values are read in the
+   <em class="replaceable"><code>expressions</code></em> or
+   <em class="replaceable"><code>condition</code></em>.
+  </p></div><div class="refsect1" id="id-1.9.3.183.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>
+      The <code class="literal">WITH</code> clause allows you to specify one or more
+      subqueries that can be referenced by name in the <code class="command">UPDATE</code>
+      query. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> and <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+      for details.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+      The name (optionally schema-qualified) of the table to update.
+      If <code class="literal">ONLY</code> is specified before the table name, matching rows
+      are updated in the named table only.  If <code class="literal">ONLY</code> is not
+      specified, matching rows are also updated in any tables inheriting from
+      the named table.  Optionally, <code class="literal">*</code> can be specified after the
+      table name to explicitly indicate that descendant tables are included.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>
+      A substitute name for the target table. When an alias is
+      provided, it completely hides the actual name of the table.  For
+      example, given <code class="literal">UPDATE foo AS f</code>, the remainder of the
+      <code class="command">UPDATE</code> statement must refer to this table as
+      <code class="literal">f</code> not <code class="literal">foo</code>.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+      The name of a column in the table named by <em class="replaceable"><code>table_name</code></em>.
+      The column name can be qualified with a subfield name or array
+      subscript, if needed.  Do not include the table's name in the
+      specification of a target column — for example,
+      <code class="literal">UPDATE table_name SET table_name.col = 1</code> is invalid.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+      An expression to assign to the column.  The expression can use the
+      old values of this and other columns in the table.
+     </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+      Set the column to its default value (which will be NULL if no specific
+      default expression has been assigned to it).  An identity column will be
+      set to a new value generated by the associated sequence.  For a
+      generated column, specifying this is permitted but merely specifies the
+      normal behavior of computing the column from its generation expression.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>sub-SELECT</code></em></span></dt><dd><p>
+      A <code class="literal">SELECT</code> sub-query that produces as many output columns
+      as are listed in the parenthesized column list preceding it.  The
+      sub-query must yield no more than one row when executed.  If it
+      yields one row, its column values are assigned to the target columns;
+      if it yields no rows, NULL values are assigned to the target columns.
+      The sub-query can refer to old values of the current row of the table
+      being updated.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>from_item</code></em></span></dt><dd><p>
+      A table expression allowing columns from other tables to appear in
+      the <code class="literal">WHERE</code> condition and update expressions. This
+      uses the same syntax as the <a class="link" href="sql-select.html#SQL-FROM" title="FROM Clause"><code class="literal">FROM</code></a> clause of
+      a <code class="command">SELECT</code> statement;
+      for example, an alias for the table name can be specified.  Do not
+      repeat the target table as a <em class="replaceable"><code>from_item</code></em>
+      unless you intend a self-join (in which case it must appear with
+      an alias in the <em class="replaceable"><code>from_item</code></em>).
+     </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+      An expression that returns a value of type <code class="type">boolean</code>.
+      Only rows for which this expression returns <code class="literal">true</code>
+      will be updated.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+      The name of the cursor to use in a <code class="literal">WHERE CURRENT OF</code>
+      condition.  The row to be updated is the one most recently fetched
+      from this cursor.  The cursor must be a non-grouping
+      query on the <code class="command">UPDATE</code>'s target table.
+      Note that <code class="literal">WHERE CURRENT OF</code> cannot be
+      specified together with a Boolean condition.  See
+      <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>
+      for more information about using cursors with
+      <code class="literal">WHERE CURRENT OF</code>.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>output_expression</code></em></span></dt><dd><p>
+      An expression to be computed and returned by the <code class="command">UPDATE</code>
+      command after each row is updated.  The expression can use any
+      column names of the table named by <em class="replaceable"><code>table_name</code></em>
+      or table(s) listed in <code class="literal">FROM</code>.
+      Write <code class="literal">*</code> to return all columns.
+     </p></dd><dt><span class="term"><em class="replaceable"><code>output_name</code></em></span></dt><dd><p>
+      A name to use for a returned column.
+     </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.183.7"><h2>Outputs</h2><p>
+   On successful completion, an <code class="command">UPDATE</code> command returns a command
+   tag of the form
+</p><pre class="screen">
+UPDATE <em class="replaceable"><code>count</code></em>
+</pre><p>
+   The <em class="replaceable"><code>count</code></em> is the number
+   of rows updated, including matched rows whose values did not change.
+   Note that the number may be less than the number of rows that matched
+   the <em class="replaceable"><code>condition</code></em> when
+   updates were suppressed by a <code class="literal">BEFORE UPDATE</code> trigger.  If
+   <em class="replaceable"><code>count</code></em> is 0, no rows were
+   updated by the query (this is not considered an error).
+  </p><p>
+   If the <code class="command">UPDATE</code> command contains a <code class="literal">RETURNING</code>
+   clause, the result will be similar to that of a <code class="command">SELECT</code>
+   statement containing the columns and values defined in the
+   <code class="literal">RETURNING</code> list, computed over the row(s) updated by the
+   command.
+  </p></div><div class="refsect1" id="id-1.9.3.183.8"><h2>Notes</h2><p>
+   When a <code class="literal">FROM</code> clause is present, what essentially happens
+   is that the target table is joined to the tables mentioned in the
+   <em class="replaceable"><code>from_item</code></em> list, and each output row of the join
+   represents an update operation for the target table.  When using
+   <code class="literal">FROM</code> you should ensure that the join
+   produces at most one output row for each row to be modified.  In
+   other words, a target row shouldn't join to more than one row from
+   the other table(s).  If it does, then only one of the join rows
+   will be used to update the target row, but which one will be used
+   is not readily predictable.
+  </p><p>
+   Because of this indeterminacy, referencing other tables only within
+   sub-selects is safer, though often harder to read and slower than
+   using a join.
+  </p><p>
+   In the case of a partitioned table, updating a row might cause it to no
+   longer satisfy the partition constraint of the containing partition. In that
+   case, if there is some other partition in the partition tree for which this
+   row satisfies its partition constraint, then the row is moved to that
+   partition. If there is no such partition, an error will occur.  Behind the
+   scenes, the row movement is actually a <code class="command">DELETE</code> and
+   <code class="command">INSERT</code> operation.
+  </p><p>
+   There is a possibility that a concurrent <code class="command">UPDATE</code> or
+   <code class="command">DELETE</code> on the row being moved will get a serialization
+   failure error.  Suppose session 1 is performing an <code class="command">UPDATE</code>
+   on a partition key, and meanwhile a concurrent session 2 for which this
+   row is visible performs an <code class="command">UPDATE</code> or
+   <code class="command">DELETE</code> operation on this row.  In such case,
+   session 2's <code class="command">UPDATE</code> or <code class="command">DELETE</code> will
+   detect the row movement and raise a serialization failure error (which
+   always returns with an SQLSTATE code '40001').  Applications may wish to
+   retry the transaction if this occurs.  In the usual case where the table
+   is not partitioned, or where there is no row movement, session 2 would
+   have identified the newly updated row and carried out the
+   <code class="command">UPDATE</code>/<code class="command">DELETE</code> on this new row
+    version.
+  </p><p>
+   Note that while rows can be moved from local partitions to a foreign-table
+   partition (provided the foreign data wrapper supports tuple routing), they
+   cannot be moved from a foreign-table partition to another partition.
+  </p><p>
+   An attempt of moving a row from one partition to another will fail if a
+   foreign key is found to directly reference an ancestor of the source
+   partition that is not the same as the ancestor that's mentioned in the
+   <code class="command">UPDATE</code> query.
+  </p></div><div class="refsect1" id="id-1.9.3.183.9"><h2>Examples</h2><p>
+   Change the word <code class="literal">Drama</code> to <code class="literal">Dramatic</code> in the
+   column <code class="structfield">kind</code> of the table <code class="structname">films</code>:
+
+</p><pre class="programlisting">
+UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama';
+</pre><p>
+  </p><p>
+   Adjust temperature entries and reset precipitation to its default
+   value in one row of the table <code class="structname">weather</code>:
+
+</p><pre class="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';
+</pre><p>
+  </p><p>
+   Perform the same operation and return the updated entries:
+
+</p><pre class="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;
+</pre><p>
+  </p><p>
+   Use the alternative column-list syntax to do the same update:
+</p><pre class="programlisting">
+UPDATE weather SET (temp_lo, temp_hi, prcp) = (temp_lo+1, temp_lo+15, DEFAULT)
+  WHERE city = 'San Francisco' AND date = '2003-07-03';
+</pre><p>
+  </p><p>
+   Increment the sales count of the salesperson who manages the
+   account for Acme Corporation, using the <code class="literal">FROM</code>
+   clause syntax:
+</p><pre class="programlisting">
+UPDATE employees SET sales_count = sales_count + 1 FROM accounts
+  WHERE accounts.name = 'Acme Corporation'
+  AND employees.id = accounts.sales_person;
+</pre><p>
+  </p><p>
+   Perform the same operation, using a sub-select in the
+   <code class="literal">WHERE</code> clause:
+</p><pre class="programlisting">
+UPDATE employees SET sales_count = sales_count + 1 WHERE id =
+  (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation');
+</pre><p>
+  </p><p>
+   Update contact names in an accounts table to match the currently assigned
+   salespeople:
+</p><pre class="programlisting">
+UPDATE accounts SET (contact_first_name, contact_last_name) =
+    (SELECT first_name, last_name FROM employees
+     WHERE employees.id = accounts.sales_person);
+</pre><p>
+   A similar result could be accomplished with a join:
+</p><pre class="programlisting">
+UPDATE accounts SET contact_first_name = first_name,
+                    contact_last_name = last_name
+  FROM employees WHERE employees.id = accounts.sales_person;
+</pre><p>
+   However, the second query may give unexpected results
+   if <code class="structname">employees</code>.<code class="structfield">id</code> is not a unique key, whereas
+   the first query is guaranteed to raise an error if there are multiple
+   <code class="structfield">id</code> matches.  Also, if there is no match for a particular
+   <code class="structname">accounts</code>.<code class="structfield">sales_person</code> entry, the first query
+   will set the corresponding name fields to NULL, whereas the second query
+   will not update that row at all.
+  </p><p>
+   Update statistics in a summary table to match the current data:
+</p><pre class="programlisting">
+UPDATE summary s SET (sum_x, sum_y, avg_x, avg_y) =
+    (SELECT sum(x), sum(y), avg(x), avg(y) FROM data d
+     WHERE d.group_id = s.group_id);
+</pre><p>
+  </p><p>
+   Attempt to insert a new stock item along with the quantity of stock. If
+   the item already exists, instead update the stock count of the existing
+   item. To do this without failing the entire transaction, use savepoints:
+</p><pre class="programlisting">
+BEGIN;
+-- other operations
+SAVEPOINT sp1;
+INSERT INTO wines VALUES('Chateau Lafite 2003', '24');
+-- Assume the above fails because of a unique key violation,
+-- so now we issue these commands:
+ROLLBACK TO sp1;
+UPDATE wines SET stock = stock + 24 WHERE winename = 'Chateau Lafite 2003';
+-- continue with other operations, and eventually
+COMMIT;
+</pre><p>
+  </p><p>
+   Change the <code class="structfield">kind</code> column of the table
+   <code class="structname">films</code> in the row on which the cursor
+   <code class="literal">c_films</code> is currently positioned:
+</p><pre class="programlisting">
+UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films;
+</pre></div><div class="refsect1" id="id-1.9.3.183.10"><h2>Compatibility</h2><p>
+   This command conforms to the <acronym class="acronym">SQL</acronym> standard, except
+   that the <code class="literal">FROM</code> and <code class="literal">RETURNING</code> clauses
+   are <span class="productname">PostgreSQL</span> extensions, as is the ability
+   to use <code class="literal">WITH</code> with <code class="command">UPDATE</code>.
+  </p><p>
+   Some other database systems offer a <code class="literal">FROM</code> option in which
+   the target table is supposed to be listed again within <code class="literal">FROM</code>.
+   That is not how <span class="productname">PostgreSQL</span> interprets
+   <code class="literal">FROM</code>.  Be careful when porting applications that use this
+   extension.
+  </p><p>
+   According to the standard, the source value for a parenthesized sub-list of
+   target column names can be any row-valued expression yielding the correct
+   number of columns.  <span class="productname">PostgreSQL</span> only allows the
+   source value to be a <a class="link" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">row
+   constructor</a> or a sub-<code class="literal">SELECT</code>.  An individual column's
+   updated value can be specified as <code class="literal">DEFAULT</code> in the
+   row-constructor case, but not inside a sub-<code class="literal">SELECT</code>.
+  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-unlisten.html" title="UNLISTEN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-vacuum.html" title="VACUUM">Next</a></td></tr><tr><td width="40%" align="left" valign="top">UNLISTEN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> VACUUM</td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-16 19:46:48 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-16 19:46:48 +0000
commit	311bcfc6b3acdd6fd152798c7f287ddf74fa2a98 (patch)
tree	0ec307299b1dada3701e42f4ca6eda57d708261e /doc/src/sgml/html/sql-update.html
parent	Initial commit. (diff)
download	postgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.tar.xz postgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.zip