postgres/doc/src/sgml/ref/insert.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.28 2005/01/04 00:39:53 tgl Exp $
PostgreSQL documentation
-->

<refentry id="SQL-INSERT">
 <refmeta>
  <refentrytitle id="SQL-INSERT-TITLE">INSERT</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>INSERT</refname>
  <refpurpose>create new rows in a table</refpurpose>
 </refnamediv>

 <indexterm zone="sql-insert">
  <primary>INSERT</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
    { DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) | <replaceable class="PARAMETER">query</replaceable> }
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>INSERT</command> inserts new rows into a table.
   One can insert a single row specified by value expressions,
   or several rows as a result of a query.
  </para>

  <para>
   The target column names may be listed in any order.  If no list of
   column names is given at all, the default is all the columns of the
   table in their declared order; or the first <replaceable>N</> column
   names, if there are only <replaceable>N</> columns supplied by the
   <literal>VALUES</> clause or <replaceable>query</>.  The values
   supplied by the <literal>VALUES</> clause or <replaceable>query</> are
   associated with the explicit or implicit column list left-to-right.
  </para>

  <para>
   Each column not present in the explicit or implicit column list will be
   filled with a default value, either its declared default value
   or null if there is none.
  </para>

  <para>
   If the expression for any column is not of the correct data type,
   automatic type conversion will be attempted.
  </para>

  <para>
   You must have <literal>INSERT</literal> privilege to a table in
   order to insert into it.  If you use the <replaceable
   class="PARAMETER">query</replaceable> clause to insert rows from a
   query, you also need to have <literal>SELECT</literal> privilege on
   any table used in the query.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="PARAMETER">table</replaceable></term>
    <listitem>
     <para>
      The name (optionally schema-qualified) of an existing table.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">column</replaceable></term>
    <listitem>
     <para>
      The name of a column in <replaceable class="PARAMETER">table</replaceable>.
      The column name can be qualified with a subfield name or array
      subscript, if needed.  (Inserting into only some fields of a
      composite column leaves the other fields null.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>DEFAULT VALUES</literal></term>
    <listitem>
     <para>
      All columns will be filled with their default values.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">expression</replaceable></term>
    <listitem>
     <para>
      An expression or value to assign to the corresponding <replaceable
      class="PARAMETER">column</replaceable>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>DEFAULT</literal></term>
    <listitem>
     <para>
      The corresponding <replaceable>column</replaceable> will be filled with
      its default value.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">query</replaceable></term>
    <listitem>
     <para>
      A query (<command>SELECT</command> statement) that supplies the
      rows to be inserted.  Refer to the <command>SELECT</command>
      statement for a description of the syntax.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Outputs</title>

  <para>
   On successful completion, an <command>INSERT</> command returns a command
   tag of the form
<screen>
INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable>
</screen>
   The <replaceable class="parameter">count</replaceable> is the number
   of rows inserted.  If <replaceable class="parameter">count</replaceable>
   is exactly one, and the target table has OIDs, then
   <replaceable class="parameter">oid</replaceable> is the
   <acronym>OID</acronym> assigned to the inserted row.  Otherwise
   <replaceable class="parameter">oid</replaceable> is zero.
  </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 second 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>
   The third 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>
   This example inserts several rows into table
   <literal>films</literal> from table <literal>tmp</literal>:

<programlisting>
INSERT INTO films SELECT * FROM tmp;
</programlisting>
  </para>

  <para>
   This example inserts into array columns:

<programlisting>
-- Create an empty 3x3 gameboard for noughts-and-crosses
-- (these commands create the same board)
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1,'{{"","",""},{"","",""},{"","",""}}');
INSERT INTO tictactoe (game, board)
    VALUES (2,'{{,,},{,,},{,,}}');
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>INSERT</command> conforms to the SQL standard.  The case in
   which a column name list is omitted, but not all the columns are
   filled from the <literal>VALUES</> clause or <replaceable>query</>,
   is disallowed by the standard.
  </para>

  <para>
   Possible limitations of the <replaceable
   class="PARAMETER">query</replaceable> clause are documented under
   <xref linkend="sql-select" endterm="sql-select-title">.
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->