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

   1 <REFENTRY ID="SQL-INSERT">
   2 <REFMETA>
   3 <REFENTRYTITLE>
   4 INSERT
   5 </REFENTRYTITLE>
   6 <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
   7 </REFMETA>
   8 <REFNAMEDIV>
   9 <REFNAME>
  10 INSERT
  11 </REFNAME>
  12 <REFPURPOSE>
  13 Inserts new rows into a table
  14 </REFPURPOSE>
  15 <REFSYNOPSISDIV>
  16 <REFSYNOPSISDIVINFO>
  17 <DATE>1998-09-02</DATE>
  18 </REFSYNOPSISDIVINFO>
  19 <SYNOPSIS>
  20 INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
  21     { VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> }
  22 </SYNOPSIS>
  23
  24 <REFSECT2 ID="R2-SQL-INSERT-1">
  25 <REFSECT2INFO>
  26 <DATE>1998-04-15</DATE>
  27 </REFSECT2INFO>
  28 <TITLE>
  29 Inputs
  30 </TITLE>
  31 <PARA>
  32 </PARA>
  33 <VARIABLELIST>
  34 <VARLISTENTRY>
  35 <TERM>
  36 <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  37 </TERM>
  38 <LISTITEM>
  39 <PARA>
  40 The name of an existing table.
  41
  42 <VARLISTENTRY>
  43 <TERM>
  44 <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
  45 </TERM>
  46 <LISTITEM>
  47 <PARA>
  48 The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
  49
  50 <VARLISTENTRY>
  51 <TERM>
  52 <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
  53 </TERM>
  54 <LISTITEM>
  55 <PARA>
  56 A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>.
  57
  58 <VARLISTENTRY>
  59 <TERM>
  60 <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
  61 </TERM>
  62 <LISTITEM>
  63 <PARA>
  64 A valid query. Refer to the SELECT statement for a further description
  65           of valid arguments.
  66
  67 </VARIABLELIST>
  68
  69 </REFSECT2>
  70
  71 <REFSECT2 ID="R2-SQL-INSERT-2">
  72 <REFSECT2INFO>
  73 <DATE>1998-04-15</DATE>
  74 </REFSECT2INFO>
  75 <TITLE>
  76 Outputs
  77 </TITLE>
  78 <PARA>
  79 </PARA>
  80 <VARIABLELIST>
  81 <VARLISTENTRY>
  82 <TERM>
  83 INSERT <ReturnValue>oid</ReturnValue> 1
  84 </TERM>
  85 <LISTITEM>
  86 <PARA>
  87 Message returned if only one row was inserted.
  88 <ReturnValue>oid</ReturnValue> is the row identifier.
  89
  90 <VARLISTENTRY>
  91 <TERM>
  92 INSERT 0 <ReturnValue>#</ReturnValue>
  93 </TERM>
  94 <LISTITEM>
  95 <PARA>
  96 Message returned if more than one rows were inserted.
  97 <ReturnValue>#</ReturnValue> is the number of rows inserted.
  98
  99 </VARIABLELIST>
 100
 101 </REFSECT2>
 102 </REFSYNOPSISDIV>
 103
 104 <REFSECT1 ID="R1-SQL-INSERT-1">
 105 <REFSECT1INFO>
 106 <DATE>1998-09-02</DATE>
 107 </REFSECT1INFO>
 108 <TITLE>
 109 Description
 110 </TITLE>
 111 <PARA>
 112    INSERT allows one to insert new rows into a table. One can insert
 113    a single row at time or several rows as a result of a query.
 114    The columns in the target list may be listed in any order.
 115    In every column not present in the target list will be inserted
 116    the default value, if column has not a declared default value
 117    it will be assumed as NULL. If the expression for each column
 118    is not of the correct data type, automatic type coercion will be
 119    attempted.
 120
 121 <para>
 122    You must have insert privilege to a table in order to append
 123    to it, as well as select privilege on any table specified
 124    in a WHERE clause.
 125
 126 <REFSECT1 ID="R1-SQL-INSERT-2">
 127 <TITLE>
 128 Usage
 129 </TITLE>
 130 <PARA>
 131 <ProgramListing>
 132    --Insert a single row into table films;
 133    --(in the second example the column date_prod is omitted
 134    --therefore will be stored in it a default value of NULL):
 135    --
 136    INSERT INTO films VALUES
 137    ('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute');
 138
 139    INSERT INTO films (code, title, did, date_prod, kind)
 140    VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama');
 141 </ProgramListing>
 142
 143 <ProgramListing>
 144    --Insert a single row into table distributors, note that
 145    --only column "name" is specified, to the non specified
 146    --column "did" will be assigned its default value:
 147    --
 148    INSERT INTO distributors (name) VALUES ('British Lion');
 149 </ProgramListing>
 150
 151 <ProgramListing>
 152    --Insert several rows into table films from table tmp:
 153    --
 154    INSERT INTO films
 155        SELECT * FROM tmp;
 156 </ProgramListing>
 157
 158 <ProgramListing>
 159    --Insert into arrays:
 160    --Create an empty 3x3 gameboard for noughts-and-crosses
 161    --(all of these queries create the same board attribute)
 162    --(Refer to PostgreSQL User's Guide chapter 7 for further
 163    --information about arrays).
 164
 165    INSERT INTO tictactoe (game, board[1:3][1:3])
 166                   VALUES (1,'{{"","",""},{},{"",""}}');
 167    INSERT INTO tictactoe (game, board[3][3])
 168                   VALUES (2,'{}');
 169    INSERT INTO tictactoe (game, board)
 170                   VALUES (3,'{{,,},{,,},{,,}}');
 171 </ProgramListing>
 172
 173 </REFSECT1>
 174
 175 <REFSECT1 ID="R1-SQL-INSERT-3">
 176 <TITLE>
 177 Compatibility
 178 </TITLE>
 179 <PARA>
 180 </PARA>
 181
 182 <REFSECT2 ID="R2-SQL-INSERT-4">
 183 <REFSECT2INFO>
 184 <DATE>1998-04-15</DATE>
 185 </REFSECT2INFO>
 186 <TITLE>
 187 SQL92
 188 </TITLE>
 189 <PARA>
 190 The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
 191 Possible limitations in features of the
 192 <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
 193 clause are documented for the SELECT statement.
 194
 195 </REFENTRY>
 196
 197 <!--
 198 <REPLACEABLE CLASS="PARAMETER">
 199 </REPLACEABLE>
 200 <ReturnValue></ReturnValue>
 201 <PARA>
 202 </PARA>
 203 <VARIABLELIST>
 204 <VARLISTENTRY>
 205 <TERM>&bull;
 206 </TERM>
 207 <LISTITEM>
 208 <PARA>
 209 </PARA>
 210 </LISTITEM>
 211 </VARLISTENTRY>
 212 </VARIABLELIST>
 213 <PARA>
 214 </PARA>
 215 -->