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