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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.33 2006/07/02 02:23:18 momjian Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATETABLEAS">
   7  <refmeta>
   8   <refentrytitle id="sql-createtableas-title">CREATE TABLE AS</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE TABLE AS</refname>
  14   <refpurpose>define a new table from the results of a query</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createtableas">
  18   <primary>CREATE TABLE AS</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable>
  24     [ (<replaceable>column_name</replaceable> [, ...] ) ]
  25     [ WITH OIDS | WITHOUT OIDS ]
  26     [ WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>) ]
  27     [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
  28     [ TABLESPACE <replaceable class="PARAMETER">tablespace</replaceable> ]
  29     AS <replaceable>query</replaceable>
  30 </synopsis>
  31  </refsynopsisdiv>
  32
  33  <refsect1>
  34   <title>Description</title>
  35
  36   <para>
  37    <command>CREATE TABLE AS</command> creates a table and fills it
  38    with data computed by a <command>SELECT</command> command or an
  39    <command>EXECUTE</command> that runs a prepared
  40    <command>SELECT</command> command.  The table columns have the
  41    names and data types associated with the output columns of the
  42    <command>SELECT</command> (except that you can override the column
  43    names by giving an explicit list of new column names).
  44   </para>
  45
  46   <para>
  47    <command>CREATE TABLE AS</command> bears some resemblance to
  48    creating a view, but it is really quite different: it creates a new
  49    table and evaluates the query just once to fill the new table
  50    initially.  The new table will not track subsequent changes to the
  51    source tables of the query.  In contrast, a view re-evaluates its
  52    defining <command>SELECT</command> statement whenever it is
  53    queried.
  54   </para>
  55  </refsect1>
  56
  57  <refsect1>
  58   <title>Parameters</title>
  59
  60   <variablelist>
  61    <varlistentry>
  62     <term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term>
  63     <listitem>
  64      <para>
  65       Ignored for compatibility. Refer to <xref
  66       linkend="sql-createtable" endterm="sql-createtable-title"> for
  67       details.
  68      </para>
  69     </listitem>
  70    </varlistentry>
  71   </variablelist>
  72
  73   <variablelist>
  74    <varlistentry>
  75     <term><literal>TEMPORARY</> or <literal>TEMP</></term>
  76     <listitem>
  77      <para>
  78       If specified, the table is created as a temporary table.
  79       Refer to <xref linkend="sql-createtable" endterm="sql-createtable-title"> for details.
  80      </para>
  81     </listitem>
  82    </varlistentry>
  83
  84    <varlistentry>
  85     <term><replaceable>table_name</replaceable></term>
  86     <listitem>
  87      <para>
  88       The name (optionally schema-qualified) of the table to be created.
  89      </para>
  90     </listitem>
  91    </varlistentry>
  92
  93    <varlistentry>
  94     <term><replaceable>column_name</replaceable></term>
  95     <listitem>
  96      <para>
  97       The name of a column in the new table.  If column names are not
  98       provided, they are taken from the output column names of the
  99       query.  If the table is created from an
 100       <command>EXECUTE</command> command, a column name list cannot be
 101       specified.
 102      </para>
 103     </listitem>
 104    </varlistentry>
 105
 106    <varlistentry>
 107     <term><literal>WITH OIDS</literal></term>
 108     <term><literal>WITHOUT OIDS</literal></term>
 109      <listitem>
 110       <para>
 111        This optional clause specifies whether the table created by
 112        <command>CREATE TABLE AS</command> should include OIDs. If
 113        neither form of this clause is specified, the value of the
 114        <xref linkend="guc-default-with-oids"> configuration parameter is
 115        used.
 116       </para>
 117      </listitem>
 118    </varlistentry>
 119
 120    <varlistentry>
 121     <term><literal>WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>)</literal></term>
 122     <listitem>
 123      <para>
 124       This optional clause specifies the table's fillfactor in percentage.
 125      </para>
 126     </listitem>
 127    </varlistentry>
 128
 129    <varlistentry>
 130     <term><literal>ON COMMIT</literal></term>
 131     <listitem>
 132      <para>
 133       The behavior of temporary tables at the end of a transaction
 134       block can be controlled using <literal>ON COMMIT</literal>.
 135       The three options are:
 136
 137       <variablelist>
 138        <varlistentry>
 139         <term><literal>PRESERVE ROWS</literal></term>
 140         <listitem>
 141          <para>
 142           No special action is taken at the ends of transactions.
 143           This is the default behavior.
 144          </para>
 145         </listitem>
 146        </varlistentry>
 147
 148        <varlistentry>
 149         <term><literal>DELETE ROWS</literal></term>
 150         <listitem>
 151          <para>
 152           All rows in the temporary table will be deleted at the end
 153           of each transaction block.  Essentially, an automatic <xref
 154           linkend="sql-truncate" endterm="sql-truncate-title"> is done
 155           at each commit.
 156          </para>
 157         </listitem>
 158        </varlistentry>
 159
 160        <varlistentry>
 161         <term><literal>DROP</literal></term>
 162         <listitem>
 163          <para>
 164           The temporary table will be dropped at the end of the current
 165           transaction block.
 166          </para>
 167         </listitem>
 168        </varlistentry>
 169       </variablelist>
 170      </para>
 171     </listitem>
 172    </varlistentry>
 173
 174    <varlistentry>
 175     <term><literal>TABLESPACE <replaceable class="PARAMETER">tablespace</replaceable></literal></term>
 176     <listitem>
 177      <para>
 178       The <replaceable class="PARAMETER">tablespace</replaceable> is the name
 179       of the tablespace in which the new table is to be created.
 180       If not specified,
 181       <xref linkend="guc-default-tablespace"> is used, or the database's
 182       default tablespace if <varname>default_tablespace</> is an empty
 183       string.
 184      </para>
 185     </listitem>
 186    </varlistentry>
 187
 188    <varlistentry>
 189     <term><replaceable>query</replaceable></term>
 190     <listitem>
 191      <para>
 192       A query statement (that is, a <command>SELECT</command> command
 193       or an <command>EXECUTE</command> command that runs a prepared
 194       <command>SELECT</command> command).  Refer to <xref
 195       linkend="sql-select" endterm="sql-select-title"> or <xref
 196       linkend="sql-execute" endterm="sql-execute-title">,
 197       respectively, for a description of the allowed syntax.
 198      </para>
 199     </listitem>
 200    </varlistentry>
 201   </variablelist>
 202  </refsect1>
 203
 204  <refsect1>
 205   <title>Notes</title>
 206
 207   <para>
 208    This command is functionally similar to <xref
 209    linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is
 210    preferred since it is less likely to be confused with other uses of
 211    the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE
 212    TABLE AS</command> offers a superset of the functionality offered
 213    by <command>SELECT INTO</command>.
 214   </para>
 215
 216   <para>
 217    Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
 218    TABLE AS</command> always included OIDs in the table it
 219    created.  As of <productname>PostgreSQL</productname> 8.0,
 220    the <command>CREATE TABLE AS</command> command allows the user to
 221    explicitly specify whether OIDs should be included. If the
 222    presence of OIDs is not explicitly specified,
 223    the <xref linkend="guc-default-with-oids"> configuration variable is
 224    used.  As of <productname>PostgreSQL</productname> 8.1,
 225    this variable is false by default, so the default behavior is not
 226    identical to pre-8.0 releases.  Applications that
 227    require OIDs in the table created by <command>CREATE TABLE
 228    AS</command> should explicitly specify <literal>WITH OIDS</literal>
 229    to ensure proper behavior.
 230   </para>
 231  </refsect1>
 232
 233  <refsect1>
 234   <title>Examples</title>
 235
 236   <para>
 237    Create a new table <literal>films_recent</literal> consisting of only
 238    recent entries from the table <literal>films</literal>:
 239
 240 <programlisting>
 241 CREATE TABLE films_recent AS
 242   SELECT * FROM films WHERE date_prod &gt;= '2002-01-01';
 243 </programlisting>
 244   </para>
 245
 246   <para>
 247    Create a new temporary table that will be dropped at commit
 248    <literal>films_recent</literal> with oids consisting of only
 249    recent entries from the table <literal>films</literal> using a
 250    prepared statement:
 251
 252 <programlisting>
 253 PREPARE recentfilms(date) AS
 254   SELECT * FROM films WHERE date_prod &gt; $1;
 255 CREATE TEMP TABLE films_recent WITH OIDS ON COMMIT DROP AS
 256   EXECUTE recentfilms('2002-01-01');
 257 </programlisting>
 258   </para>
 259  </refsect1>
 260
 261  <refsect1>
 262   <title>Compatibility</title>
 263
 264   <para>
 265    <command>CREATE TABLE AS</command> conforms to the <acronym>SQL</acronym>
 266    standard, with the following exceptions:
 267
 268    <itemizedlist spacing="compact">
 269     <listitem>
 270      <para>
 271       The standard requires parentheses around the subquery clause; in
 272       <productname>PostgreSQL</productname>, these parentheses are
 273       optional.
 274      </para>
 275     </listitem>
 276
 277     <listitem>
 278      <para>
 279       The standard defines a <literal>WITH [ NO ] DATA</literal> clause;
 280       this is not currently implemented by <productname>PostgreSQL</>.
 281       The behavior provided by <productname>PostgreSQL</> is equivalent
 282       to the standard's <literal>WITH DATA</literal> case.
 283      </para>
 284     </listitem>
 285
 286     <listitem>
 287      <para>
 288       <literal>WITH/WITHOUT OIDS</> is a <productname>PostgreSQL</>
 289       extension.
 290      </para>
 291     </listitem>
 292
 293     <listitem>
 294      <para>
 295       <productname>PostgreSQL</> handles temporary tables in a way
 296       rather different from the standard; see
 297       <xref linkend="sql-createtable" endterm="sql-createtable-title">
 298       for details.
 299      </para>
 300     </listitem>
 301
 302     <listitem>
 303      <para>
 304       The <productname>PostgreSQL</productname> concept of tablespaces is not
 305       part of the standard.  Hence, the clause <literal>TABLESPACE</literal>
 306       is an extension.
 307      </para>
 308     </listitem>
 309    </itemizedlist>
 310   </para>
 311  </refsect1>
 312
 313  <refsect1>
 314   <title>See Also</title>
 315
 316   <simplelist type="inline">
 317    <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
 318    <member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
 319    <member><xref linkend="sql-select" endterm="sql-select-title"></member>
 320    <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>
 321   </simplelist>
 322  </refsect1>
 323
 324 </refentry>
 325
 326 <!-- Keep this comment at the end of the file
 327 Local variables:
 328 mode: sgml
 329 sgml-omittag:nil
 330 sgml-shorttag:t
 331 sgml-minimize-attributes:nil
 332 sgml-always-quote-attributes:t
 333 sgml-indent-step:1
 334 sgml-indent-data:t
 335 sgml-parent-document:nil
 336 sgml-default-dtd-file:"../reference.ced"
 337 sgml-exposed-tags:nil
 338 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 339 sgml-local-ecat-files:nil
 340 End:
 341 -->