バージョンごとのドキュメント一覧

6.4. 更新された行のデータを返す #

<title>Returning Data from Modified Rows</title>

Sometimes it is useful to obtain data from modified rows while they are being manipulated. The <command>INSERT</command>, <command>UPDATE</command>, <command>DELETE</command>, and <command>MERGE</command> commands all have an optional <literal>RETURNING</literal> clause that supports this. Use of <literal>RETURNING</literal> avoids performing an extra database query to collect the data, and is especially valuable when it would otherwise be difficult to identify the modified rows reliably. 行が更新されるときに、その行のデータを取得できると便利なことがあります。 INSERTUPDATEDELETEMERGEの各コマンドは、いずれもオプションのRETURNING句によりそれが可能となっています。 RETURNINGを使うことで、行を取得するために余分なデータベースへの問い合わせを行うことを避けられ、それ以外の方法で更新された行を確実に特定するのが難しい場合には、これは特に貴重です。

The allowed contents of a <literal>RETURNING</literal> clause are the same as a <command>SELECT</command> command's output list (see <xref linkend="queries-select-lists"/>). It can contain column names of the command's target table, or value expressions using those columns. A common shorthand is <literal>RETURNING *</literal>, which selects all columns of the target table in order. RETURNING句で使用できる項目はSELECTコマンドの出力リスト(7.3参照)と同じです。 コマンドの対象となっているテーブルの列名、あるいはそれらの列を使った値の式を入れることができます。 よく使われる省略記法はRETURNING *で、これは対象テーブルのすべての列を順に返します。

In an <command>INSERT</command>, the default data available to <literal>RETURNING</literal> is the row as it was inserted. This is not so useful in trivial inserts, since it would just repeat the data provided by the client. But it can be very handy when relying on computed default values. For example, when using a <link linkend="datatype-serial"><type>serial</type></link> column to provide unique identifiers, <literal>RETURNING</literal> can return the ID assigned to a new row: 《マッチ度[93.374741]》INSERTでは、RETURNINGで利用できるデータは、挿入された通りの行です。 単純な挿入では、クライアントが提供したデータを単に繰り返すだけになりますから、あまり役には立ちません。 しかし、計算されたデフォルト値に依存しているときは、これは非常に便利なことがあります。 例えばserialの列を使って一意識別子を提供している場合、以下のようにRETURNINGによって、新しい行に割り当てられたIDを返すことができます。

CREATE TABLE users (firstname text, lastname text, id serial primary key);

INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id;

The <literal>RETURNING</literal> clause is also very useful with <literal>INSERT ... SELECT</literal>. また、RETURNING句はINSERT ... SELECTでも非常に役に立ちます。

In an <command>UPDATE</command>, the default data available to <literal>RETURNING</literal> is the new content of the modified row. For example: 《マッチ度[89.583333]》UPDATEでは、RETURNINGで利用できるデータは、更新された行の新しい内容です。 例を示します。 《機械翻訳》UPDATEでは、RETURNINGに利用可能なデフォルトデータは、修正された行の新しいコンテンツです。 例の場合:。

UPDATE products SET price = price * 1.10
  WHERE price <= 99.99
  RETURNING name, price AS new_price;

In a <command>DELETE</command>, the default data available to <literal>RETURNING</literal> is the content of the deleted row. For example: 《マッチ度[89.130435]》DELETEでは、RETURNINGで利用できるデータは、削除された行の内容です。 例を示します。 《機械翻訳》DELETEでは、RETURNINGに利用可能なデフォルトデータは、削除された行のコンテンツです。 例の場合:。

DELETE FROM products
  WHERE obsoletion_date = 'today'
  RETURNING *;

In a <command>MERGE</command>, the default data available to <literal>RETURNING</literal> is the content of the source row plus the content of the inserted, updated, or deleted target row. Since it is quite common for the source and target to have many of the same columns, specifying <literal>RETURNING *</literal> can lead to a lot of duplicated columns, so it is often more useful to qualify it so as to return just the source or target row. For example: 《マッチ度[93.873085]》MERGEでは、RETURNINGで利用できるデータは、元となる行の内容と挿入、更新、または削除された対象行の内容です。 元となるものと対象が多くの同じ列を持つことは非常に一般的であるため、RETURNING *を指定すると、多くの重複した列が発生する可能性があります。そのため、元となる行または対象行だけを返すように修飾するのがより有用なことがしばしばあります。 例を示します。

MERGE INTO products p USING new_products n ON p.product_no = n.product_no
  WHEN NOT MATCHED THEN INSERT VALUES (n.product_no, n.name, n.price)
  WHEN MATCHED THEN UPDATE SET name = n.name, price = n.price
  RETURNING p.*;

In each of these commands, it is also possible to explicitly return the old and new content of the modified row. For example: 《機械翻訳》これらの各コマンドでは、変更されたコンテンツの新旧の行を明示的に結果することもできます。 例の場合:。

UPDATE products SET price = price * 1.10
  WHERE price <= 99.99
  RETURNING name, old.price AS old_price, new.price AS new_price,
            new.price - old.price AS price_change;

In this example, writing <literal>new.price</literal> is the same as just writing <literal>price</literal>, but it makes the meaning clearer. 《機械翻訳》この例では、書くことnew.priceは単に書くことpriceと同じですが、意味をより明確にします。

This syntax for returning old and new values is available in <command>INSERT</command>, <command>UPDATE</command>, <command>DELETE</command>, and <command>MERGE</command> commands, but typically old values will be <literal>NULL</literal> for an <command>INSERT</command>, and new values will be <literal>NULL</literal> for a <command>DELETE</command>. However, there are situations where it can still be useful for those commands. For example, in an <command>INSERT</command> with an <link linkend="sql-on-conflict"><literal>ON CONFLICT DO UPDATE</literal></link> clause, the old values will be non-<literal>NULL</literal> for conflicting rows. Similarly, if a <command>DELETE</command> is turned into an <command>UPDATE</command> by a <link linkend="sql-createrule">rewrite rule</link>, the new values may be non-<literal>NULL</literal>. 《機械翻訳》古い値と新しい値を返すためのこの構文は、INSERTUPDATEDELETE、およびMERGEコマンドで使用できますが、一般的に古い値はINSERTに対してNULLになり、新しい値はDELETEに対してNULLになります。 ただし、これらのコマンドに対しても有用な状況があります。 例の場合、ON CONFLICT DO UPDATE句を持つINSERTでは、競合する行に対して古い値は非NULLになります。 同様に、書き換えルールによってDELETEUPDATEになった場合、新しい値は非NULLになる可能性があります。

If there are triggers (<xref linkend="triggers"/>) on the target table, the data available to <literal>RETURNING</literal> is the row as modified by the triggers. Thus, inspecting columns computed by triggers is another common use-case for <literal>RETURNING</literal>. 対象のテーブルにトリガ(第37章)がある場合、RETURNINGで利用できるデータは、トリガで更新された行です。 従って、トリガによって計算された列を検査するのもRETURNINGの一般的な利用方法の一つです。