<refentry id="SQL-INSERT">
 <refmeta>
  <refentrytitle>
   INSERT
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   INSERT
  </refname>
  <refpurpose>
   Inserts new rows into a table
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1998-09-23</date>
  </refsynopsisdivinfo>
  <synopsis>
INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
    { VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) | SELECT <replaceable class="PARAMETER">query</replaceable> }
  </synopsis>
  
  <refsect2 id="R2-SQL-INSERT-1">
   <refsect2info>
    <date>1998-09-23</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">table</replaceable></term>
      <listitem>
       <para>
	The name 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>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">expression</replaceable></term>
      <listitem>
       <para>
	A valid expression or value to assign to <replaceable
	 class="PARAMETER">column</replaceable>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">query</replaceable></term>
      <listitem>
       <para>
	A valid query. Refer to the SELECT statement for a further description
	of valid arguments.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
  
  <refsect2 id="R2-SQL-INSERT-2">
   <refsect2info>
    <date>1998-09-23</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
INSERT <replaceable>oid</replaceable> 1
       </computeroutput></term>
      <listitem>
       <para>
	Message returned if only one row was inserted.
	<returnvalue><replaceable>oid</replaceable></returnvalue>
	is the numeric <acronym>OID</acronym> of the inserted row.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
INSERT 0 <replaceable>#</replaceable>
       </computeroutput></term>
      <listitem>
       <para>
	Message returned if more than one rows were inserted.
	<returnvalue><replaceable>#</replaceable></returnvalue>
	is the number of rows inserted.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-INSERT-1">
  <refsect1info>
   <date>1998-09-02</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>INSERT</command> allows one to insert new rows into a table. One can insert
   a single row at time or several rows as a result of a query.
   The columns in the target list may be listed in any order.
   In every column not present in the target list will be inserted 
   the default value, if column has not a declared default value
   it will be assumed as NULL. If the expression for each column
   is not of the correct data type, automatic type coercion will be
   attempted.
  </para>
  <para>
   You must have insert privilege to a table in order to append
   to it, as well as select privilege on any table specified
   in a WHERE clause.
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-INSERT-2">
  <title>
   Usage
  </title>
  <para>
   Insert a single row into table <literal>films</literal>:

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

  <para>
   In this second example the column <literal>date_prod</literal> is
   omitted and therefore it will have the default value of NULL:

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

  <para>
   Insert a single row into table distributors; note that
   only column <literal>name</literal> is specified, so the omitted
   column <literal>did</literal> will be assigned its default value:

   <programlisting>
INSERT INTO distributors (name) VALUES ('British Lion');
   </programlisting>
  </para>

  <para>
   Insert several rows into table films from table <literal>tmp</literal>:

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

  <para>
   Insert into arrays (refer to <citetitle>The PostgreSQL User's Guide</citetitle> for further
   information about arrays):
		
   <programlisting>
-- Create an empty 3x3 gameboard for noughts-and-crosses
-- (all of these queries create the same board attribute)
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3])
    VALUES (2,'{}');
INSERT INTO tictactoe (game, board)
    VALUES (3,'{{,,},{,,},{,,}}');
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-INSERT-3">
  <title>
   Compatibility
  </title>
  <para>
  </para>
	
  <refsect2 id="R2-SQL-INSERT-4">
   <refsect2info>
    <date>1998-09-23</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    <command>INSERT</command> is fully compatible with <acronym>SQL92</acronym>.
    Possible limitations in features of the 
    <replaceable class="PARAMETER">query</replaceable>
    clause are documented for the SELECT statement.
   </para>
  </refsect2>
 </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:
-->
