begriffs open source - ai-pg/blob - full-docs/html/dml-returning.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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>6.4. Returning Data from Modified Rows</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="dml-delete.html" title="6.3. Deleting Data" /><link rel="next" href="queries.html" title="Chapter 7. Queries" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">6.4. Returning Data from Modified Rows</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml-delete.html" title="6.3. Deleting Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><th width="60%" align="center">Chapter 6. Data Manipulation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries.html" title="Chapter 7. Queries">Next</a></td></tr></table><hr /></div><div class="sect1" id="DML-RETURNING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">6.4. Returning Data from Modified Rows <a href="#DML-RETURNING" class="id_link">#</a></h2></div></div></div><a id="id-1.5.5.6.2" class="indexterm"></a><a id="id-1.5.5.6.3" class="indexterm"></a><a id="id-1.5.5.6.4" class="indexterm"></a><a id="id-1.5.5.6.5" class="indexterm"></a><a id="id-1.5.5.6.6" class="indexterm"></a><p>
   3    Sometimes it is useful to obtain data from modified rows while they are
   4    being manipulated.  The <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
   5    <code class="command">DELETE</code>, and <code class="command">MERGE</code> commands all have an
   6    optional <code class="literal">RETURNING</code> clause that supports this.  Use
   7    of <code class="literal">RETURNING</code> avoids performing an extra database query to
   8    collect the data, and is especially valuable when it would otherwise be
   9    difficult to identify the modified rows reliably.
  10   </p><p>
  11    The allowed contents of a <code class="literal">RETURNING</code> clause are the same as
  12    a <code class="command">SELECT</code> command's output list
  13    (see <a class="xref" href="queries-select-lists.html" title="7.3. Select Lists">Section 7.3</a>).  It can contain column
  14    names of the command's target table, or value expressions using those
  15    columns.  A common shorthand is <code class="literal">RETURNING *</code>, which selects
  16    all columns of the target table in order.
  17   </p><p>
  18    In an <code class="command">INSERT</code>, the default data available to
  19    <code class="literal">RETURNING</code> is
  20    the row as it was inserted.  This is not so useful in trivial inserts,
  21    since it would just repeat the data provided by the client.  But it can
  22    be very handy when relying on computed default values.  For example,
  23    when using a <a class="link" href="datatype-numeric.html#DATATYPE-SERIAL" title="8.1.4. Serial Types"><code class="type">serial</code></a>
  24    column to provide unique identifiers, <code class="literal">RETURNING</code> can return
  25    the ID assigned to a new row:
  26 </p><pre class="programlisting">
  27 CREATE TABLE users (firstname text, lastname text, id serial primary key);
  28
  29 INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id;
  30 </pre><p>
  31    The <code class="literal">RETURNING</code> clause is also very useful
  32    with <code class="literal">INSERT ... SELECT</code>.
  33   </p><p>
  34    In an <code class="command">UPDATE</code>, the default data available to
  35    <code class="literal">RETURNING</code> is
  36    the new content of the modified row.  For example:
  37 </p><pre class="programlisting">
  38 UPDATE products SET price = price * 1.10
  39   WHERE price &lt;= 99.99
  40   RETURNING name, price AS new_price;
  41 </pre><p>
  42   </p><p>
  43    In a <code class="command">DELETE</code>, the default data available to
  44    <code class="literal">RETURNING</code> is
  45    the content of the deleted row.  For example:
  46 </p><pre class="programlisting">
  47 DELETE FROM products
  48   WHERE obsoletion_date = 'today'
  49   RETURNING *;
  50 </pre><p>
  51   </p><p>
  52    In a <code class="command">MERGE</code>, the default data available to
  53    <code class="literal">RETURNING</code> is
  54    the content of the source row plus the content of the inserted, updated, or
  55    deleted target row.  Since it is quite common for the source and target to
  56    have many of the same columns, specifying <code class="literal">RETURNING *</code>
  57    can lead to a lot of duplicated columns, so it is often more useful to
  58    qualify it so as to return just the source or target row.  For example:
  59 </p><pre class="programlisting">
  60 MERGE INTO products p USING new_products n ON p.product_no = n.product_no
  61   WHEN NOT MATCHED THEN INSERT VALUES (n.product_no, n.name, n.price)
  62   WHEN MATCHED THEN UPDATE SET name = n.name, price = n.price
  63   RETURNING p.*;
  64 </pre><p>
  65   </p><p>
  66    In each of these commands, it is also possible to explicitly return the
  67    old and new content of the modified row.  For example:
  68 </p><pre class="programlisting">
  69 UPDATE products SET price = price * 1.10
  70   WHERE price &lt;= 99.99
  71   RETURNING name, old.price AS old_price, new.price AS new_price,
  72             new.price - old.price AS price_change;
  73 </pre><p>
  74    In this example, writing <code class="literal">new.price</code> is the same as
  75    just writing <code class="literal">price</code>, but it makes the meaning clearer.
  76   </p><p>
  77    This syntax for returning old and new values is available in
  78    <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
  79    <code class="command">DELETE</code>, and <code class="command">MERGE</code> commands, but
  80    typically old values will be <code class="literal">NULL</code> for an
  81    <code class="command">INSERT</code>, and new values will be <code class="literal">NULL</code>
  82    for a <code class="command">DELETE</code>.  However, there are situations where it
  83    can still be useful for those commands.  For example, in an
  84    <code class="command">INSERT</code> with an
  85    <a class="link" href="sql-insert.html#SQL-ON-CONFLICT" title="ON CONFLICT Clause"><code class="literal">ON CONFLICT DO UPDATE</code></a>
  86    clause, the old values will be non-<code class="literal">NULL</code> for conflicting
  87    rows.  Similarly, if a <code class="command">DELETE</code> is turned into an
  88    <code class="command">UPDATE</code> by a <a class="link" href="sql-createrule.html" title="CREATE RULE">rewrite rule</a>,
  89    the new values may be non-<code class="literal">NULL</code>.
  90   </p><p>
  91    If there are triggers (<a class="xref" href="triggers.html" title="Chapter 37. Triggers">Chapter 37</a>) on the target table,
  92    the data available to <code class="literal">RETURNING</code> is the row as modified by
  93    the triggers.  Thus, inspecting columns computed by triggers is another
  94    common use-case for <code class="literal">RETURNING</code>.
  95   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml-delete.html" title="6.3. Deleting Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries.html" title="Chapter 7. Queries">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.3. Deleting Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Queries</td></tr></table></div></body></html>