granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/insert.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.24 2003/08/31 17:32:23 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-INSERT">
   7  <refmeta>
   8   <refentrytitle id="SQL-INSERT-TITLE">INSERT</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>INSERT</refname>
  14   <refpurpose>create new rows in a table</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-insert">
  18   <primary>INSERT</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
  24     { DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) | <replaceable class="PARAMETER">query</replaceable> }
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>INSERT</command> allows one to insert new rows into a
  33    table. One can insert
  34    a single row at a time or several rows as a result of a query.
  35   </para>
  36
  37   <para>
  38    The columns in the target list may be listed in any order.
  39    Each column not present in the target list will be inserted
  40    using a default value, either its declared default value
  41    or null.
  42   </para>
  43
  44   <para>
  45    If the expression for each column is not of the correct data type,
  46    automatic type conversion will be attempted.
  47   </para>
  48
  49   <para>
  50    You must have <literal>INSERT</literal> privilege to a table in
  51    order to insert into it.  If you use the <replaceable
  52    class="PARAMETER">query</replaceable> clause to insert rows from a
  53    query, you also need to have <literal>SELECT</literal> privilege on
  54    any table used in the query.
  55   </para>
  56  </refsect1>
  57
  58  <refsect1>
  59   <title>Parameters</title>
  60
  61   <variablelist>
  62    <varlistentry>
  63     <term><replaceable class="PARAMETER">table</replaceable></term>
  64     <listitem>
  65      <para>
  66       The name (optionally schema-qualified) of an existing table.
  67      </para>
  68     </listitem>
  69    </varlistentry>
  70
  71    <varlistentry>
  72     <term><replaceable class="PARAMETER">column</replaceable></term>
  73     <listitem>
  74      <para>
  75       The name of a column in <replaceable class="PARAMETER">table</replaceable>.
  76      </para>
  77     </listitem>
  78    </varlistentry>
  79
  80    <varlistentry>
  81     <term><literal>DEFAULT VALUES</literal></term>
  82     <listitem>
  83      <para>
  84       All columns will be filled with their default values.
  85      </para>
  86     </listitem>
  87    </varlistentry>
  88
  89    <varlistentry>
  90     <term><replaceable class="PARAMETER">expression</replaceable></term>
  91     <listitem>
  92      <para>
  93       An expression or value to assign to <replaceable
  94       class="PARAMETER">column</replaceable>.
  95      </para>
  96     </listitem>
  97    </varlistentry>
  98
  99    <varlistentry>
 100     <term><literal>DEFAULT</literal></term>
 101     <listitem>
 102      <para>
 103       This column will be filled with its default value.
 104      </para>
 105     </listitem>
 106    </varlistentry>
 107
 108    <varlistentry>
 109     <term><replaceable class="PARAMETER">query</replaceable></term>
 110     <listitem>
 111      <para>
 112       A query (<command>SELECT</command> statement) that supplies the
 113       rows to be inserted.  Refer to the <command>SELECT</command>
 114       statement for a description of the syntax.
 115      </para>
 116     </listitem>
 117    </varlistentry>
 118   </variablelist>
 119  </refsect1>
 120
 121  <refsect1>
 122   <title>Diagnostics</title>
 123
 124   <variablelist>
 125    <varlistentry>
 126     <term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term>
 127     <listitem>
 128      <para>
 129       Message returned if only one row was inserted.
 130       <returnvalue><replaceable>oid</replaceable></returnvalue> is the
 131       <acronym>OID</acronym> of the inserted row.
 132      </para>
 133     </listitem>
 134    </varlistentry>
 135
 136    <varlistentry>
 137     <term><computeroutput>INSERT 0 <replaceable>count</replaceable></computeroutput></term>
 138     <listitem>
 139      <para>
 140       Message returned if more than one rows were inserted.
 141       <replaceable>count</replaceable> is the number of rows inserted.
 142      </para>
 143     </listitem>
 144    </varlistentry>
 145   </variablelist>
 146  </refsect1>
 147
 148  <refsect1>
 149   <title>Examples</title>
 150
 151   <para>
 152    Insert a single row into table <literal>films</literal>:
 153
 154 <programlisting>
 155 INSERT INTO films VALUES
 156     ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
 157 </programlisting>
 158   </para>
 159
 160   <para>
 161    In this second example, the last column <literal>len</literal> is
 162    omitted and therefore it will have the default value of null:
 163
 164 <programlisting>
 165 INSERT INTO films (code, title, did, date_prod, kind)
 166     VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
 167 </programlisting>
 168   </para>
 169
 170   <para>
 171    The third example uses the <literal>DEFAULT</literal> clause for
 172    the date columns rather than specifying a value:
 173
 174 <programlisting>
 175 INSERT INTO films VALUES
 176     ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
 177 INSERT INTO films (code, title, did, date_prod, kind)
 178     VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');
 179 </programlisting>
 180   </para>
 181
 182   <para>
 183    This examples inserts several rows into table
 184    <literal>films</literal> from table <literal>tmp</literal>:
 185
 186 <programlisting>
 187 INSERT INTO films SELECT * FROM tmp;
 188 </programlisting>
 189   </para>
 190
 191   <para>
 192    This example inserts into array columns:
 193
 194 <programlisting>
 195 -- Create an empty 3x3 gameboard for noughts-and-crosses
 196 -- (all of these commands create the same board)
 197 INSERT INTO tictactoe (game, board[1:3][1:3])
 198     VALUES (1,'{{"","",""},{},{"",""}}');
 199 INSERT INTO tictactoe (game, board[3][3])
 200     VALUES (2,'{}');
 201 INSERT INTO tictactoe (game, board)
 202     VALUES (3,'{{,,},{,,},{,,}}');
 203 </programlisting>
 204   </para>
 205  </refsect1>
 206
 207  <refsect1>
 208   <title>Compatibility</title>
 209
 210   <para>
 211    <command>INSERT</command> conforms fully to the SQL standard.
 212    Possible limitations of the <replaceable
 213    class="PARAMETER">query</replaceable> clause are documented under
 214    <xref linkend="sql-select" endterm="sql-select-title">.
 215   </para>
 216  </refsect1>
 217 </refentry>
 218
 219 <!-- Keep this comment at the end of the file
 220 Local variables:
 221 mode: sgml
 222 sgml-omittag:nil
 223 sgml-shorttag:t
 224 sgml-minimize-attributes:nil
 225 sgml-always-quote-attributes:t
 226 sgml-indent-step:1
 227 sgml-indent-data:t
 228 sgml-parent-document:nil
 229 sgml-default-dtd-file:"../reference.ced"
 230 sgml-exposed-tags:nil
 231 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 232 sgml-local-ecat-files:nil
 233 End:
 234 -->