Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Watch 1
Star 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 0f75e31513
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/sql-insert.html

465 lines
32KB
Raw Blame History 

  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>INSERT</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 V1.79.1" /><link rel="prev" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA" /><link rel="next" href="sql-listen.html" title="LISTEN" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">INSERT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA">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 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-listen.html" title="LISTEN">Next</a></td></tr></table><hr></hr></div><div class="refentry" id="SQL-INSERT"><div class="titlepage"></div><a id="id-1.9.3.152.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">INSERT</span></h2><p>INSERT — create new rows in a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">

  3. [ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]

  4. INSERT INTO <em class="replaceable"><code>table_name</code></em> [ AS <em class="replaceable"><code>alias</code></em> ] [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]

  5.     [ OVERRIDING { SYSTEM | USER } VALUE ]

  6.     { DEFAULT VALUES | VALUES ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) [, ...] | <em class="replaceable"><code>query</code></em> }

  7.     [ ON CONFLICT [ <em class="replaceable"><code>conflict_target</code></em> ] <em class="replaceable"><code>conflict_action</code></em> ]

  8.     [ RETURNING * | <em class="replaceable"><code>output_expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]

  9. 

  10. <span class="phrase">where <em class="replaceable"><code>conflict_target</code></em> can be one of:</span>

  11. 

  12.     ( { <em class="replaceable"><code>index_column_name</code></em> | ( <em class="replaceable"><code>index_expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> ] [, ...] ) [ WHERE <em class="replaceable"><code>index_predicate</code></em> ]

  13.     ON CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>

  14. 

  15. <span class="phrase">and <em class="replaceable"><code>conflict_action</code></em> is one of:</span>

  16. 

  17.     DO NOTHING

  18.     DO UPDATE SET { <em class="replaceable"><code>column_name</code></em> = { <em class="replaceable"><code>expression</code></em> | DEFAULT } |

  19.                     ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = [ ROW ] ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) |

  20.                     ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = ( <em class="replaceable"><code>sub-SELECT</code></em> )

  21.                   } [, ...]

  22.               [ WHERE <em class="replaceable"><code>condition</code></em> ]

  23. </pre></div><div class="refsect1" id="id-1.9.3.152.5"><h2>Description</h2><p>

  24.    <code class="command">INSERT</code> inserts new rows into a table.

  25.    One can insert one or more rows specified by value expressions,

  26.    or zero or more rows resulting from a query.

  27.   </p><p>

  28.    The target column names can be listed in any order.  If no list of

  29.    column names is given at all, the default is all the columns of the

  30.    table in their declared order; or the first <em class="replaceable"><code>N</code></em> column

  31.    names, if there are only <em class="replaceable"><code>N</code></em> columns supplied by the

  32.    <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em>.  The values

  33.    supplied by the <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em> are

  34.    associated with the explicit or implicit column list left-to-right.

  35.   </p><p>

  36.    Each column not present in the explicit or implicit column list will be

  37.    filled with a default value, either its declared default value

  38.    or null if there is none.

  39.   </p><p>

  40.    If the expression for any column is not of the correct data type,

  41.    automatic type conversion will be attempted.

  42.   </p><p>

  43.    <code class="literal">ON CONFLICT</code> can be used to specify an alternative

  44.    action to raising a unique constraint or exclusion constraint

  45.    violation error. (See <a class="xref" href="sql-insert.html#SQL-ON-CONFLICT" title="ON CONFLICT Clause"><code class="literal">ON CONFLICT</code> Clause</a> below.)

  46.   </p><p>

  47.    The optional <code class="literal">RETURNING</code> clause causes <code class="command">INSERT</code>

  48.    to compute and return value(s) based on each row actually inserted

  49.    (or updated, if an <code class="literal">ON CONFLICT DO UPDATE</code> clause was

  50.    used).  This is primarily useful for obtaining values that were

  51.    supplied by defaults, such as a serial sequence number.  However,

  52.    any expression using the table's columns is allowed.  The syntax of

  53.    the <code class="literal">RETURNING</code> list is identical to that of the output

  54.    list of <code class="command">SELECT</code>.  Only rows that were successfully

  55.    inserted or updated will be returned.  For example, if a row was

  56.    locked but not updated because an <code class="literal">ON CONFLICT DO UPDATE

  57.    ... WHERE</code> clause <em class="replaceable"><code>condition</code></em> was not satisfied, the

  58.    row will not be returned.

  59.   </p><p>

  60.    You must have <code class="literal">INSERT</code> privilege on a table in

  61.    order to insert into it.  If <code class="literal">ON CONFLICT DO UPDATE</code> is

  62.    present, <code class="literal">UPDATE</code> privilege on the table is also

  63.    required.

  64.   </p><p>

  65.    If a column list is specified, you only need

  66.    <code class="literal">INSERT</code> privilege on the listed columns.

  67.    Similarly, when <code class="literal">ON CONFLICT DO UPDATE</code> is specified, you

  68.    only need <code class="literal">UPDATE</code> privilege on the column(s) that are

  69.    listed to be updated.  However, <code class="literal">ON CONFLICT DO UPDATE</code>

  70.    also requires <code class="literal">SELECT</code> privilege on any column whose

  71.    values are read in the <code class="literal">ON CONFLICT DO UPDATE</code>

  72.    expressions or <em class="replaceable"><code>condition</code></em>.

  73.   </p><p>

  74.    Use of the <code class="literal">RETURNING</code> clause requires <code class="literal">SELECT</code>

  75.    privilege on all columns mentioned in <code class="literal">RETURNING</code>.

  76.    If you use the <em class="replaceable"><code>query</code></em> clause to insert rows from a

  77.    query, you of course need to have <code class="literal">SELECT</code> privilege on

  78.    any table or column used in the query.

  79.   </p></div><div class="refsect1" id="id-1.9.3.152.6"><h2>Parameters</h2><div class="refsect2" id="SQL-INSERTING-PARAMS"><h3>Inserting</h3><p>

  80.     This section covers parameters that may be used when only

  81.     inserting new rows.  Parameters <span class="emphasis"><em>exclusively</em></span>

  82.     used with the <code class="literal">ON CONFLICT</code> clause are described

  83.     separately.

  84.    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>

  85.         The <code class="literal">WITH</code> clause allows you to specify one or more

  86.         subqueries that can be referenced by name in the <code class="command">INSERT</code>

  87.         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>

  88.         for details.

  89.        </p><p>

  90.         It is possible for the <em class="replaceable"><code>query</code></em>

  91.         (<code class="command">SELECT</code> statement)

  92.         to also contain a <code class="literal">WITH</code> clause.  In such a case both

  93.         sets of <em class="replaceable"><code>with_query</code></em> can be referenced within

  94.         the <em class="replaceable"><code>query</code></em>, but the

  95.         second one takes precedence since it is more closely nested.

  96.        </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>

  97.         The name (optionally schema-qualified) of an existing table.

  98.        </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>

  99.         A substitute name for <em class="replaceable"><code>table_name</code></em>.  When an alias is

  100.         provided, it completely hides the actual name of the table.

  101.         This is particularly useful when <code class="literal">ON CONFLICT DO UPDATE</code>

  102.         targets a table named <code class="varname">excluded</code>, since that will otherwise

  103.         be taken as the name of the special table representing rows proposed

  104.         for insertion.

  105.        </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>

  106.         The name of a column in the table named by <em class="replaceable"><code>table_name</code></em>.  The column name

  107.         can be qualified with a subfield name or array subscript, if

  108.         needed.  (Inserting into only some fields of a composite

  109.         column leaves the other fields null.)  When referencing a

  110.         column with <code class="literal">ON CONFLICT DO UPDATE</code>, do not include

  111.         the table's name in the specification of a target column.  For

  112.         example, <code class="literal">INSERT INTO table_name ... ON CONFLICT DO UPDATE

  113.         SET table_name.col = 1</code> is invalid (this follows the general

  114.         behavior for <code class="command">UPDATE</code>).

  115.        </p></dd><dt><span class="term"><code class="literal">OVERRIDING SYSTEM VALUE</code></span></dt><dd><p>

  116.         Without this clause, it is an error to specify an explicit value

  117.         (other than <code class="literal">DEFAULT</code>) for an identity column defined

  118.         as <code class="literal">GENERATED ALWAYS</code>.  This clause overrides that

  119.         restriction.

  120.        </p></dd><dt><span class="term"><code class="literal">OVERRIDING USER VALUE</code></span></dt><dd><p>

  121.         If this clause is specified, then any values supplied for identity

  122.         columns defined as <code class="literal">GENERATED BY DEFAULT</code> are ignored

  123.         and the default sequence-generated values are applied.

  124.        </p><p>

  125.         This clause is useful for example when copying values between tables.

  126.         Writing <code class="literal">INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM

  127.         tbl1</code> will copy from <code class="literal">tbl1</code> all columns that

  128.         are not identity columns in <code class="literal">tbl2</code> while values for

  129.         the identity columns in <code class="literal">tbl2</code> will be generated by

  130.         the sequences associated with <code class="literal">tbl2</code>.

  131.        </p></dd><dt><span class="term"><code class="literal">DEFAULT VALUES</code></span></dt><dd><p>

  132.         All columns will be filled with their default values.

  133.         (An <code class="literal">OVERRIDING</code> clause is not permitted in this

  134.         form.)

  135.        </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>

  136.         An expression or value to assign to the corresponding column.

  137.        </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>

  138.         The corresponding column will be filled with

  139.         its default value.

  140.        </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>

  141.         A query (<code class="command">SELECT</code> statement) that supplies the

  142.         rows to be inserted.  Refer to the

  143.         <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>

  144.         statement for a description of the syntax.

  145.        </p></dd><dt><span class="term"><em class="replaceable"><code>output_expression</code></em></span></dt><dd><p>

  146.         An expression to be computed and returned by the

  147.         <code class="command">INSERT</code> command after each row is inserted or

  148.         updated. The expression can use any column names of the table

  149.         named by <em class="replaceable"><code>table_name</code></em>.  Write

  150.         <code class="literal">*</code> to return all columns of the inserted or updated

  151.         row(s).

  152.        </p></dd><dt><span class="term"><em class="replaceable"><code>output_name</code></em></span></dt><dd><p>

  153.         A name to use for a returned column.

  154.        </p></dd></dl></div></div><div class="refsect2" id="SQL-ON-CONFLICT"><h3><code class="literal">ON CONFLICT</code> Clause</h3><a id="id-1.9.3.152.6.3.2" class="indexterm"></a><a id="id-1.9.3.152.6.3.3" class="indexterm"></a><p>

  155.     The optional <code class="literal">ON CONFLICT</code> clause specifies an

  156.     alternative action to raising a unique violation or exclusion

  157.     constraint violation error.  For each individual row proposed for

  158.     insertion, either the insertion proceeds, or, if an

  159.     <span class="emphasis"><em>arbiter</em></span> constraint or index specified by

  160.     <em class="parameter"><code>conflict_target</code></em> is violated, the

  161.     alternative <em class="parameter"><code>conflict_action</code></em> is taken.

  162.     <code class="literal">ON CONFLICT DO NOTHING</code> simply avoids inserting

  163.     a row as its alternative action.  <code class="literal">ON CONFLICT DO

  164.     UPDATE</code> updates the existing row that conflicts with the

  165.     row proposed for insertion as its alternative action.

  166.    </p><p>

  167.     <em class="parameter"><code>conflict_target</code></em> can perform

  168.     <span class="emphasis"><em>unique index inference</em></span>.  When performing

  169.     inference, it consists of one or more <em class="replaceable"><code>index_column_name</code></em> columns and/or

  170.     <em class="replaceable"><code>index_expression</code></em>

  171.     expressions, and an optional <em class="replaceable"><code>index_predicate</code></em>.  All <em class="replaceable"><code>table_name</code></em> unique indexes that,

  172.     without regard to order, contain exactly the

  173.     <em class="parameter"><code>conflict_target</code></em>-specified

  174.     columns/expressions are inferred (chosen) as arbiter indexes.  If

  175.     an <em class="replaceable"><code>index_predicate</code></em> is

  176.     specified, it must, as a further requirement for inference,

  177.     satisfy arbiter indexes.  Note that this means a non-partial

  178.     unique index (a unique index without a predicate) will be inferred

  179.     (and thus used by <code class="literal">ON CONFLICT</code>) if such an index

  180.     satisfying every other criteria is available.  If an attempt at

  181.     inference is unsuccessful, an error is raised.

  182.    </p><p>

  183.     <code class="literal">ON CONFLICT DO UPDATE</code> guarantees an atomic

  184.     <code class="command">INSERT</code> or <code class="command">UPDATE</code> outcome;

  185.     provided there is no independent error, one of those two outcomes

  186.     is guaranteed, even under high concurrency.  This is also known as

  187.     <em class="firstterm">UPSERT</em> — <span class="quote">“<span class="quote">UPDATE or

  188.     INSERT</span>”</span>.

  189.    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>conflict_target</code></em></span></dt><dd><p>

  190.         Specifies which conflicts <code class="literal">ON CONFLICT</code> takes

  191.         the alternative action on by choosing <em class="firstterm">arbiter

  192.         indexes</em>.  Either performs <span class="emphasis"><em>unique index

  193.         inference</em></span>, or names a constraint explicitly.  For

  194.         <code class="literal">ON CONFLICT DO NOTHING</code>, it is optional to

  195.         specify a <em class="parameter"><code>conflict_target</code></em>; when

  196.         omitted, conflicts with all usable constraints (and unique

  197.         indexes) are handled.  For <code class="literal">ON CONFLICT DO

  198.         UPDATE</code>, a <em class="parameter"><code>conflict_target</code></em>

  199.         <span class="emphasis"><em>must</em></span> be provided.

  200.        </p></dd><dt><span class="term"><em class="replaceable"><code>conflict_action</code></em></span></dt><dd><p>

  201.         <em class="parameter"><code>conflict_action</code></em> specifies an

  202.         alternative <code class="literal">ON CONFLICT</code> action.  It can be

  203.         either <code class="literal">DO NOTHING</code>, or a <code class="literal">DO

  204.         UPDATE</code> clause specifying the exact details of the

  205.         <code class="literal">UPDATE</code> action to be performed in case of a

  206.         conflict.  The <code class="literal">SET</code> and

  207.         <code class="literal">WHERE</code> clauses in <code class="literal">ON CONFLICT DO

  208.         UPDATE</code> have access to the existing row using the

  209.         table's name (or an alias), and to rows proposed for insertion

  210.         using the special <code class="varname">excluded</code> table.

  211.         <code class="literal">SELECT</code> privilege is required on any column in the

  212.         target table where corresponding <code class="varname">excluded</code>

  213.         columns are read.

  214.        </p><p>

  215.         Note that the effects of all per-row <code class="literal">BEFORE

  216.         INSERT</code> triggers are reflected in

  217.         <code class="varname">excluded</code> values, since those effects may

  218.         have contributed to the row being excluded from insertion.

  219.        </p></dd><dt><span class="term"><em class="replaceable"><code>index_column_name</code></em></span></dt><dd><p>

  220.         The name of a <em class="replaceable"><code>table_name</code></em> column.  Used to

  221.         infer arbiter indexes.  Follows <code class="command">CREATE

  222.         INDEX</code> format.  <code class="literal">SELECT</code> privilege on

  223.         <em class="replaceable"><code>index_column_name</code></em>

  224.         is required.

  225.        </p></dd><dt><span class="term"><em class="replaceable"><code>index_expression</code></em></span></dt><dd><p>

  226.         Similar to <em class="replaceable"><code>index_column_name</code></em>, but used to

  227.         infer expressions on <em class="replaceable"><code>table_name</code></em> columns appearing

  228.         within index definitions (not simple columns).  Follows

  229.         <code class="command">CREATE INDEX</code> format.  <code class="literal">SELECT</code>

  230.         privilege on any column appearing within <em class="replaceable"><code>index_expression</code></em> is required.

  231.        </p></dd><dt><span class="term"><em class="replaceable"><code>collation</code></em></span></dt><dd><p>

  232.         When specified, mandates that corresponding <em class="replaceable"><code>index_column_name</code></em> or

  233.         <em class="replaceable"><code>index_expression</code></em>

  234.         use a particular collation in order to be matched during

  235.         inference.  Typically this is omitted, as collations usually

  236.         do not affect whether or not a constraint violation occurs.

  237.         Follows <code class="command">CREATE INDEX</code> format.

  238.        </p></dd><dt><span class="term"><em class="replaceable"><code>opclass</code></em></span></dt><dd><p>

  239.         When specified, mandates that corresponding <em class="replaceable"><code>index_column_name</code></em> or

  240.         <em class="replaceable"><code>index_expression</code></em>

  241.         use particular operator class in order to be matched during

  242.         inference.  Typically this is omitted,  as the

  243.         <span class="emphasis"><em>equality</em></span> semantics are often equivalent

  244.         across a type's operator classes anyway, or because it's

  245.         sufficient to trust that the defined unique indexes have the

  246.         pertinent definition of equality.  Follows <code class="command">CREATE

  247.         INDEX</code> format.

  248.        </p></dd><dt><span class="term"><em class="replaceable"><code>index_predicate</code></em></span></dt><dd><p>

  249.         Used to allow inference of partial unique indexes.  Any

  250.         indexes that satisfy the predicate (which need not actually be

  251.         partial indexes) can be inferred.  Follows <code class="command">CREATE

  252.         INDEX</code> format.  <code class="literal">SELECT</code> privilege on any

  253.         column appearing within <em class="replaceable"><code>index_predicate</code></em> is required.

  254.        </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>

  255.         Explicitly specifies an arbiter

  256.         <span class="emphasis"><em>constraint</em></span> by name, rather than inferring

  257.         a constraint or index.

  258.        </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>

  259.         An expression that returns a value of type

  260.         <code class="type">boolean</code>.  Only rows for which this expression

  261.         returns <code class="literal">true</code> will be updated, although all

  262.         rows will be locked when the <code class="literal">ON CONFLICT DO UPDATE</code>

  263.         action is taken.  Note that

  264.         <em class="replaceable"><code>condition</code></em> is evaluated last, after

  265.         a conflict has been identified as a candidate to update.

  266.        </p></dd></dl></div><p>

  267.     Note that exclusion constraints are not supported as arbiters with

  268.     <code class="literal">ON CONFLICT DO UPDATE</code>. In all cases, only

  269.     <code class="literal">NOT DEFERRABLE</code> constraints and unique indexes

  270.     are supported as arbiters.

  271.    </p><p>

  272.     <code class="command">INSERT</code> with an <code class="literal">ON CONFLICT DO UPDATE</code>

  273.     clause is a <span class="quote">“<span class="quote">deterministic</span>”</span> statement.  This means

  274.     that the command will not be allowed to affect any single existing

  275.     row more than once; a cardinality violation error will be raised

  276.     when this situation arises.  Rows proposed for insertion should

  277.     not duplicate each other in terms of attributes constrained by an

  278.     arbiter index or constraint.

  279.    </p><p>

  280.     Note that it is currently not supported for the

  281.     <code class="literal">ON CONFLICT DO UPDATE</code> clause of an

  282.     <code class="command">INSERT</code> applied to a partitioned table to update the

  283.     partition key of a conflicting row such that it requires the row be moved

  284.     to a new partition.

  285.    </p><div class="tip"><h3 class="title">Tip</h3><p>

  286.      It is often preferable to use unique index inference rather than

  287.      naming a constraint directly using <code class="literal">ON CONFLICT ON

  288.      CONSTRAINT</code> <em class="replaceable"><code>

  289.      constraint_name</code></em>.  Inference will continue to work

  290.      correctly when the underlying index is replaced by another more

  291.      or less equivalent index in an overlapping way, for example when

  292.      using <code class="literal">CREATE UNIQUE INDEX ...  CONCURRENTLY</code>

  293.      before dropping the index being replaced.

  294.     </p></div></div></div><div class="refsect1" id="id-1.9.3.152.7"><h2>Outputs</h2><p>

  295.    On successful completion, an <code class="command">INSERT</code> command returns a command

  296.    tag of the form

  297. </p><pre class="screen">

  298. INSERT <em class="replaceable"><code>oid</code></em> <em class="replaceable"><code>count</code></em>

  299. </pre><p>

  300.    The <em class="replaceable"><code>count</code></em> is the number of

  301.    rows inserted or updated.  <em class="replaceable"><code>oid</code></em> is always 0 (it

  302.    used to be the <acronym class="acronym">OID</acronym> assigned to the inserted row if

  303.    <em class="replaceable"><code>count</code></em> was exactly one and the target table was

  304.    declared <code class="literal">WITH OIDS</code> and 0 otherwise, but creating a table

  305.    <code class="literal">WITH OIDS</code> is not supported anymore).

  306.   </p><p>

  307.    If the <code class="command">INSERT</code> command contains a <code class="literal">RETURNING</code>

  308.    clause, the result will be similar to that of a <code class="command">SELECT</code>

  309.    statement containing the columns and values defined in the

  310.    <code class="literal">RETURNING</code> list, computed over the row(s) inserted or

  311.    updated by the command.

  312.   </p></div><div class="refsect1" id="id-1.9.3.152.8"><h2>Notes</h2><p>

  313.    If the specified table is a partitioned table, each row is routed to

  314.    the appropriate partition and inserted into it.  If the specified table

  315.    is a partition, an error will occur if one of the input rows violates

  316.    the partition constraint.

  317.   </p></div><div class="refsect1" id="id-1.9.3.152.9"><h2>Examples</h2><p>

  318.    Insert a single row into table <code class="literal">films</code>:

  319. 

  320. </p><pre class="programlisting">

  321. INSERT INTO films VALUES

  322.     ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');

  323. </pre><p>

  324.   </p><p>

  325.    In this example, the <code class="literal">len</code> column is

  326.    omitted and therefore it will have the default value:

  327. 

  328. </p><pre class="programlisting">

  329. INSERT INTO films (code, title, did, date_prod, kind)

  330.     VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

  331. </pre><p>

  332.   </p><p>

  333.    This example uses the <code class="literal">DEFAULT</code> clause for

  334.    the date columns rather than specifying a value:

  335. 

  336. </p><pre class="programlisting">

  337. INSERT INTO films VALUES

  338.     ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');

  339. INSERT INTO films (code, title, did, date_prod, kind)

  340.     VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

  341. </pre><p>

  342.   </p><p>

  343.    To insert a row consisting entirely of default values:

  344. 

  345. </p><pre class="programlisting">

  346. INSERT INTO films DEFAULT VALUES;

  347. </pre><p>

  348.   </p><p>

  349.    To insert multiple rows using the multirow <code class="command">VALUES</code> syntax:

  350. 

  351. </p><pre class="programlisting">

  352. INSERT INTO films (code, title, did, date_prod, kind) VALUES

  353.     ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),

  354.     ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');

  355. </pre><p>

  356.   </p><p>

  357.    This example inserts some rows into table

  358.    <code class="literal">films</code> from a table <code class="literal">tmp_films</code>

  359.    with the same column layout as <code class="literal">films</code>:

  360. 

  361. </p><pre class="programlisting">

  362. INSERT INTO films SELECT * FROM tmp_films WHERE date_prod &lt; '2004-05-07';

  363. </pre><p>

  364.   </p><p>

  365.    This example inserts into array columns:

  366. 

  367. </p><pre class="programlisting">

  368. -- Create an empty 3x3 gameboard for noughts-and-crosses

  369. INSERT INTO tictactoe (game, board[1:3][1:3])

  370.     VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');

  371. -- The subscripts in the above example aren't really needed

  372. INSERT INTO tictactoe (game, board)

  373.     VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

  374. </pre><p>

  375.   </p><p>

  376.    Insert a single row into table <code class="literal">distributors</code>, returning

  377.    the sequence number generated by the <code class="literal">DEFAULT</code> clause:

  378. 

  379. </p><pre class="programlisting">

  380. INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')

  381.    RETURNING did;

  382. </pre><p>

  383.   </p><p>

  384.    Increment the sales count of the salesperson who manages the

  385.    account for Acme Corporation, and record the whole updated row

  386.    along with current time in a log table:

  387. </p><pre class="programlisting">

  388. WITH upd AS (

  389.   UPDATE employees SET sales_count = sales_count + 1 WHERE id =

  390.     (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')

  391.     RETURNING *

  392. )

  393. INSERT INTO employees_log SELECT *, current_timestamp FROM upd;

  394. </pre><p>

  395.   </p><p>

  396.    Insert or update new distributors as appropriate.  Assumes a unique

  397.    index has been defined that constrains values appearing in the

  398.    <code class="literal">did</code> column.  Note that the special

  399.    <code class="varname">excluded</code> table is used to reference values originally

  400.    proposed for insertion:

  401. </p><pre class="programlisting">

  402. INSERT INTO distributors (did, dname)

  403.     VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')

  404.     ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;

  405. </pre><p>

  406.   </p><p>

  407.    Insert a distributor, or do nothing for rows proposed for insertion

  408.    when an existing, excluded row (a row with a matching constrained

  409.    column or columns after before row insert triggers fire) exists.

  410.    Example assumes a unique index has been defined that constrains

  411.    values appearing in the <code class="literal">did</code> column:

  412. </p><pre class="programlisting">

  413. INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH')

  414.     ON CONFLICT (did) DO NOTHING;

  415. </pre><p>

  416.   </p><p>

  417.    Insert or update new distributors as appropriate.  Example assumes

  418.    a unique index has been defined that constrains values appearing in

  419.    the <code class="literal">did</code> column.  <code class="literal">WHERE</code> clause is

  420.    used to limit the rows actually updated (any existing row not

  421.    updated will still be locked, though):

  422. </p><pre class="programlisting">

  423. -- Don't update existing distributors based in a certain ZIP code

  424. INSERT INTO distributors AS d (did, dname) VALUES (8, 'Anvil Distribution')

  425.     ON CONFLICT (did) DO UPDATE

  426.     SET dname = EXCLUDED.dname || ' (formerly ' || d.dname || ')'

  427.     WHERE d.zipcode &lt;&gt; '21201';

  428. 

  429. -- Name a constraint directly in the statement (uses associated

  430. -- index to arbitrate taking the DO NOTHING action)

  431. INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')

  432.     ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

  433. </pre><p>

  434.   </p><p>

  435.    Insert new distributor if possible;  otherwise

  436.    <code class="literal">DO NOTHING</code>.  Example assumes a unique index has been

  437.    defined that constrains values appearing in the

  438.    <code class="literal">did</code> column on a subset of rows where the

  439.    <code class="literal">is_active</code> Boolean column evaluates to

  440.    <code class="literal">true</code>:

  441. </p><pre class="programlisting">

  442. -- This statement could infer a partial unique index on "did"

  443. -- with a predicate of "WHERE is_active", but it could also

  444. -- just use a regular unique constraint on "did"

  445. INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')

  446.     ON CONFLICT (did) WHERE is_active DO NOTHING;

  447. </pre></div><div class="refsect1" id="id-1.9.3.152.10"><h2>Compatibility</h2><p>

  448.    <code class="command">INSERT</code> conforms to the SQL standard, except that

  449.    the <code class="literal">RETURNING</code> clause is a

  450.    <span class="productname">PostgreSQL</span> extension, as is the ability

  451.    to use <code class="literal">WITH</code> with <code class="command">INSERT</code>, and the ability to

  452.    specify an alternative action with <code class="literal">ON CONFLICT</code>.

  453.    Also, the case in

  454.    which a column name list is omitted, but not all the columns are

  455.    filled from the <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em>,

  456.    is disallowed by the standard.

  457.   </p><p>

  458.    The SQL standard specifies that <code class="literal">OVERRIDING SYSTEM VALUE</code>

  459.    can only be specified if an identity column that is generated always

  460.    exists.  PostgreSQL allows the clause in any case and ignores it if it is

  461.    not applicable.

  462.   </p><p>

  463.    Possible limitations of the <em class="replaceable"><code>query</code></em> clause are documented under

  464.    <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>.

  465.   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-importforeignschema.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-listen.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">IMPORT FOREIGN SCHEMA </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> LISTEN</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1