partition, an error will occur if one of the input rows violates
   the partition constraint.
  </para>

  <para>
   You may also wish to consider using <command>MERGE</command>, since that
   allows mixing <command>INSERT</command>, <command>UPDATE</command>, and
   <command>DELETE</command> within a single statement.
   See <xref linkend="sql-merge"/>.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Insert a single row into table <literal>films</literal>:

<programlisting>
INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
</programlisting>
  </para>

  <para>
   In this example, the <literal>len</literal> column is
   omitted and therefore it will have the default value:

<programlisting>
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
</programlisting>
  </para>

  <para>
   This example uses the <literal>DEFAULT</literal> clause for
   the date columns rather than specifying a value:

<programlisting>
INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');
</programlisting>
  </para>

  <para>
   To insert a row consisting entirely of default values:

<programlisting>
INSERT INTO films DEFAULT VALUES;
</programlisting>
  </para>

  <para>
   To insert multiple rows using the multirow <command>VALUES</command> syntax:

<programlisting>
INSERT INTO films (code, title, did, date_prod, kind) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');
</programlisting>
  </para>

  <para>
   This example inserts some rows into table
   <literal>films</literal> from a table <literal>tmp_films</literal>
   with the same column layout as <literal>films</literal>:

<programlisting>
INSERT INTO films SELECT * FROM tmp_films WHERE date_prod &lt; '2004-05-07';
</programlisting>
  </para>

  <para>
   This example inserts into array columns:

<programlisting>
-- Create an empty 3x3 gameboard for noughts-and-crosses
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- The subscripts in the above example aren't really needed
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');
</programlisting>
  </para>

  <para>
   Insert a single row into table <literal>distributors</literal>, returning
   the sequence number generated by the <literal>DEFAULT</literal> clause:

<programlisting>
INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;
</programlisting>
  </para>

  <para>
   Increment the sales count of the salesperson who manages the
   account for Acme Corporation, and record the whole updated row
   along with current time in a log table:
<programlisting>
WITH upd AS (
  UPDATE employees SET sales_count = sales_count + 1 WHERE id =
    (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
    RETURNING *
)
INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
</programlisting>
  </para>
  <para>
   Insert or update new distributors as appropriate.  Assumes a unique
   index has been defined that constrains values appearing in the
   <literal>did</literal> column.  Note that the special
   <varname>excluded</varname> table is used to reference values originally
   proposed for insertion:
<programlisting>
INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;
</programlisting>
  </para>
  <para>
   Insert or update new distributors as above, returning information
   about any existing