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.26 2004/12/13 18:05:10 petere 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> [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
  24     AS <replaceable>query</replaceable>
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>CREATE TABLE AS</command> creates a table and fills it
  33    with data computed by a <command>SELECT</command> command or an
  34    <command>EXECUTE</command> that runs a prepared
  35    <command>SELECT</command> command.  The table columns have the
  36    names and data types associated with the output columns of the
  37    <command>SELECT</command> (except that you can override the column
  38    names by giving an explicit list of new column names).
  39   </para>
  40
  41   <para>
  42    <command>CREATE TABLE AS</command> bears some resemblance to
  43    creating a view, but it is really quite different: it creates a new
  44    table and evaluates the query just once to fill the new table
  45    initially.  The new table will not track subsequent changes to the
  46    source tables of the query.  In contrast, a view re-evaluates its
  47    defining <command>SELECT</command> statement whenever it is
  48    queried.
  49   </para>
  50  </refsect1>
  51
  52  <refsect1>
  53   <title>Parameters</title>
  54
  55   <variablelist>
  56    <varlistentry>
  57     <term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term>
  58     <listitem>
  59      <para>
  60       Ignored for compatibility. Refer to <xref
  61       linkend="sql-createtable" endterm="sql-createtable-title"> for
  62       details.
  63      </para>
  64     </listitem>
  65    </varlistentry>
  66   </variablelist>
  67
  68   <variablelist>
  69    <varlistentry>
  70     <term><literal>TEMPORARY</> or <literal>TEMP</></term>
  71     <listitem>
  72      <para>
  73       If specified, the table is created as a temporary table.
  74       Refer to <xref linkend="sql-createtable" endterm="sql-createtable-title"> for details.
  75      </para>
  76     </listitem>
  77    </varlistentry>
  78
  79    <varlistentry>
  80     <term><replaceable>table_name</replaceable></term>
  81     <listitem>
  82      <para>
  83       The name (optionally schema-qualified) of the table to be created.
  84      </para>
  85     </listitem>
  86    </varlistentry>
  87
  88    <varlistentry>
  89     <term><replaceable>column_name</replaceable></term>
  90     <listitem>
  91      <para>
  92       The name of a column in the new table.  If column names are not
  93       provided, they are taken from the output column names of the
  94       query.  If the table is created out of an
  95       <command>EXECUTE</command> command, a column name list can
  96       currently not be specified.
  97      </para>
  98     </listitem>
  99    </varlistentry>
 100
 101    <varlistentry>
 102     <term><literal>WITH OIDS</literal></term>
 103     <term><literal>WITHOUT OIDS</literal></term>
 104      <listitem>
 105       <para>
 106        This optional clause specifies whether the table created by
 107        <command>CREATE TABLE AS</command> should include OIDs. If
 108        neither form of this clause if specified, the value of the
 109        <xref linkend="guc-default-with-oids"> configuration parameter is
 110        used.
 111       </para>
 112      </listitem>
 113    </varlistentry>
 114
 115    <varlistentry>
 116     <term><replaceable>query</replaceable></term>
 117     <listitem>
 118      <para>
 119       A query statement (that is, a <command>SELECT</command> command
 120       or an <command>EXECUTE</command> command that runs a prepared
 121       <command>SELECT</command> command).  Refer to <xref
 122       linkend="sql-select" endterm="sql-select-title"> or <xref
 123       linkend="sql-execute" endterm="sql-execute-title">,
 124       respectively, for a description of the allowed syntax.
 125      </para>
 126     </listitem>
 127    </varlistentry>
 128   </variablelist>
 129  </refsect1>
 130
 131  <refsect1>
 132   <title>Notes</title>
 133
 134   <para>
 135    This command is functionally similar to <xref
 136    linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is
 137    preferred since it is less likely to be confused with other uses of
 138    the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE
 139    TABLE AS</command> offers a superset of the functionality offered
 140    by <command>SELECT INTO</command>.
 141   </para>
 142
 143   <para>
 144    Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
 145    TABLE AS</command> always included OIDs in the table it
 146    produced. Furthermore, these OIDs were newly generated: they were
 147    distinct from the OIDs of any of the rows in the source tables of
 148    the <command>SELECT</command> or <command>EXECUTE</command>
 149    statement. Therefore, if <command>CREATE TABLE AS</command> was
 150    frequently executed, the OID counter would be rapidly
 151    incremented. As of <productname>PostgresSQL</productname> 8.0,
 152    the <command>CREATE TABLE AS</command> command allows the user to
 153    explicitly specify whether OIDs should be included. If the
 154    presence of OIDs is not explicitly specified,
 155    the <xref linkend="guc-default-with-oids"> configuration variable is
 156    used. While this variable currently defaults to true, the default
 157    value may be changed in the future. Therefore, applications that
 158    require OIDs in the table created by <command>CREATE TABLE
 159    AS</command> should explicitly specify <literal>WITH
 160    OIDS</literal> to ensure compatibility with future versions
 161    of <productname>PostgreSQL</productname>.
 162   </para>
 163  </refsect1>
 164
 165  <refsect1>
 166   <title>Compatibility</title>
 167
 168   <para>
 169    <command>CREATE TABLE AS</command> is specified by the SQL:2003
 170    standard. There are some small differences between the definition
 171    of the command in SQL:2003 and its implementation in
 172    <productname>PostgreSQL</>:
 173
 174    <itemizedlist spacing="compact">
 175     <listitem>
 176      <para>
 177       The standard requires parentheses around the subquery clause; in
 178       <productname>PostgreSQL</productname>, these parentheses are
 179       optional.
 180      </para>
 181     </listitem>
 182
 183     <listitem>
 184      <para>
 185       The standard defines an <literal>ON COMMIT</literal> clause;
 186       this is not currently implemented by <productname>PostgreSQL</>.
 187      </para>
 188     </listitem>
 189
 190     <listitem>
 191      <para>
 192       The standard defines a <literal>WITH DATA</literal> clause;
 193       this is not currently implemented by <productname>PostgreSQL</>.
 194      </para>
 195     </listitem>
 196    </itemizedlist>
 197   </para>
 198  </refsect1>
 199
 200  <refsect1>
 201   <title>See Also</title>
 202
 203   <simplelist type="inline">
 204    <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
 205    <member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
 206    <member><xref linkend="sql-select" endterm="sql-select-title"></member>
 207    <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>
 208   </simplelist>
 209  </refsect1>
 210
 211 </refentry>
 212
 213 <!-- Keep this comment at the end of the file
 214 Local variables:
 215 mode: sgml
 216 sgml-omittag:nil
 217 sgml-shorttag:t
 218 sgml-minimize-attributes:nil
 219 sgml-always-quote-attributes:t
 220 sgml-indent-step:1
 221 sgml-indent-data:t
 222 sgml-parent-document:nil
 223 sgml-default-dtd-file:"../reference.ced"
 224 sgml-exposed-tags:nil
 225 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 226 sgml-local-ecat-files:nil
 227 End:
 228 -->