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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.28 2005/01/04 00:39:53 tgl 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> inserts new rows into a table.
  33    One can insert a single row specified by value expressions,
  34    or several rows as a result of a query.
  35   </para>
  36
  37   <para>
  38    The target column names may be listed in any order.  If no list of
  39    column names is given at all, the default is all the columns of the
  40    table in their declared order; or the first <replaceable>N</> column
  41    names, if there are only <replaceable>N</> columns supplied by the
  42    <literal>VALUES</> clause or <replaceable>query</>.  The values
  43    supplied by the <literal>VALUES</> clause or <replaceable>query</> are
  44    associated with the explicit or implicit column list left-to-right.
  45   </para>
  46
  47   <para>
  48    Each column not present in the explicit or implicit column list will be
  49    filled with a default value, either its declared default value
  50    or null if there is none.
  51   </para>
  52
  53   <para>
  54    If the expression for any column is not of the correct data type,
  55    automatic type conversion will be attempted.
  56   </para>
  57
  58   <para>
  59    You must have <literal>INSERT</literal> privilege to a table in
  60    order to insert into it.  If you use the <replaceable
  61    class="PARAMETER">query</replaceable> clause to insert rows from a
  62    query, you also need to have <literal>SELECT</literal> privilege on
  63    any table used in the query.
  64   </para>
  65  </refsect1>
  66
  67  <refsect1>
  68   <title>Parameters</title>
  69
  70   <variablelist>
  71    <varlistentry>
  72     <term><replaceable class="PARAMETER">table</replaceable></term>
  73     <listitem>
  74      <para>
  75       The name (optionally schema-qualified) of an existing table.
  76      </para>
  77     </listitem>
  78    </varlistentry>
  79
  80    <varlistentry>
  81     <term><replaceable class="PARAMETER">column</replaceable></term>
  82     <listitem>
  83      <para>
  84       The name of a column in <replaceable class="PARAMETER">table</replaceable>.
  85       The column name can be qualified with a subfield name or array
  86       subscript, if needed.  (Inserting into only some fields of a
  87       composite column leaves the other fields null.)
  88      </para>
  89     </listitem>
  90    </varlistentry>
  91
  92    <varlistentry>
  93     <term><literal>DEFAULT VALUES</literal></term>
  94     <listitem>
  95      <para>
  96       All columns will be filled with their default values.
  97      </para>
  98     </listitem>
  99    </varlistentry>
 100
 101    <varlistentry>
 102     <term><replaceable class="PARAMETER">expression</replaceable></term>
 103     <listitem>
 104      <para>
 105       An expression or value to assign to the corresponding <replaceable
 106       class="PARAMETER">column</replaceable>.
 107      </para>
 108     </listitem>
 109    </varlistentry>
 110
 111    <varlistentry>
 112     <term><literal>DEFAULT</literal></term>
 113     <listitem>
 114      <para>
 115       The corresponding <replaceable>column</replaceable> will be filled with
 116       its default value.
 117      </para>
 118     </listitem>
 119    </varlistentry>
 120
 121    <varlistentry>
 122     <term><replaceable class="PARAMETER">query</replaceable></term>
 123     <listitem>
 124      <para>
 125       A query (<command>SELECT</command> statement) that supplies the
 126       rows to be inserted.  Refer to the <command>SELECT</command>
 127       statement for a description of the syntax.
 128      </para>
 129     </listitem>
 130    </varlistentry>
 131   </variablelist>
 132  </refsect1>
 133
 134  <refsect1>
 135   <title>Outputs</title>
 136
 137   <para>
 138    On successful completion, an <command>INSERT</> command returns a command
 139    tag of the form
 140 <screen>
 141 INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable>
 142 </screen>
 143    The <replaceable class="parameter">count</replaceable> is the number
 144    of rows inserted.  If <replaceable class="parameter">count</replaceable>
 145    is exactly one, and the target table has OIDs, then
 146    <replaceable class="parameter">oid</replaceable> is the
 147    <acronym>OID</acronym> assigned to the inserted row.  Otherwise
 148    <replaceable class="parameter">oid</replaceable> is zero.
 149   </para>
 150  </refsect1>
 151
 152  <refsect1>
 153   <title>Examples</title>
 154
 155   <para>
 156    Insert a single row into table <literal>films</literal>:
 157
 158 <programlisting>
 159 INSERT INTO films VALUES
 160     ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
 161 </programlisting>
 162   </para>
 163
 164   <para>
 165    In this second example, the <literal>len</literal> column is
 166    omitted and therefore it will have the default value:
 167
 168 <programlisting>
 169 INSERT INTO films (code, title, did, date_prod, kind)
 170     VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
 171 </programlisting>
 172   </para>
 173
 174   <para>
 175    The third example uses the <literal>DEFAULT</literal> clause for
 176    the date columns rather than specifying a value:
 177
 178 <programlisting>
 179 INSERT INTO films VALUES
 180     ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
 181 INSERT INTO films (code, title, did, date_prod, kind)
 182     VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');
 183 </programlisting>
 184   </para>
 185
 186   <para>
 187    This example inserts several rows into table
 188    <literal>films</literal> from table <literal>tmp</literal>:
 189
 190 <programlisting>
 191 INSERT INTO films SELECT * FROM tmp;
 192 </programlisting>
 193   </para>
 194
 195   <para>
 196    This example inserts into array columns:
 197
 198 <programlisting>
 199 -- Create an empty 3x3 gameboard for noughts-and-crosses
 200 -- (these commands create the same board)
 201 INSERT INTO tictactoe (game, board[1:3][1:3])
 202     VALUES (1,'{{"","",""},{"","",""},{"","",""}}');
 203 INSERT INTO tictactoe (game, board)
 204     VALUES (2,'{{,,},{,,},{,,}}');
 205 </programlisting>
 206   </para>
 207  </refsect1>
 208
 209  <refsect1>
 210   <title>Compatibility</title>
 211
 212   <para>
 213    <command>INSERT</command> conforms to the SQL standard.  The case in
 214    which a column name list is omitted, but not all the columns are
 215    filled from the <literal>VALUES</> clause or <replaceable>query</>,
 216    is disallowed by the standard.
 217   </para>
 218
 219   <para>
 220    Possible limitations of the <replaceable
 221    class="PARAMETER">query</replaceable> clause are documented under
 222    <xref linkend="sql-select" endterm="sql-select-title">.
 223   </para>
 224  </refsect1>
 225 </refentry>
 226
 227 <!-- Keep this comment at the end of the file
 228 Local variables:
 229 mode: sgml
 230 sgml-omittag:nil
 231 sgml-shorttag:t
 232 sgml-minimize-attributes:nil
 233 sgml-always-quote-attributes:t
 234 sgml-indent-step:1
 235 sgml-indent-data:t
 236 sgml-parent-document:nil
 237 sgml-default-dtd-file:"../reference.ced"
 238 sgml-exposed-tags:nil
 239 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 240 sgml-local-ecat-files:nil
 241 End:
 242 -->