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.28 2005/01/05 14:22:39 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 from an
  95       <command>EXECUTE</command> command, a column name list cannot be
  96       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 is 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.  As of <productname>PostgresSQL</productname> 8.0,
 147    the <command>CREATE TABLE AS</command> command allows the user to
 148    explicitly specify whether OIDs should be included. If the
 149    presence of OIDs is not explicitly specified,
 150    the <xref linkend="guc-default-with-oids"> configuration variable is
 151    used. While this variable currently defaults to true, the default
 152    value may be changed in the future. Therefore, applications that
 153    require OIDs in the table created by <command>CREATE TABLE
 154    AS</command> should explicitly specify <literal>WITH
 155    OIDS</literal> to ensure compatibility with future versions
 156    of <productname>PostgreSQL</productname>.
 157   </para>
 158  </refsect1>
 159
 160  <refsect1>
 161   <title>Compatibility</title>
 162
 163   <para>
 164    <command>CREATE TABLE AS</command> is specified by the SQL:2003
 165    standard. There are some small differences between the definition
 166    of the command in SQL:2003 and its implementation in
 167    <productname>PostgreSQL</>:
 168
 169    <itemizedlist spacing="compact">
 170     <listitem>
 171      <para>
 172       The standard requires parentheses around the subquery clause; in
 173       <productname>PostgreSQL</productname>, these parentheses are
 174       optional.
 175      </para>
 176     </listitem>
 177
 178     <listitem>
 179      <para>
 180       The standard defines an <literal>ON COMMIT</literal> clause;
 181       this is not currently implemented by <productname>PostgreSQL</>.
 182      </para>
 183     </listitem>
 184
 185     <listitem>
 186      <para>
 187       The standard defines a <literal>WITH DATA</literal> clause;
 188       this is not currently implemented by <productname>PostgreSQL</>.
 189      </para>
 190     </listitem>
 191    </itemizedlist>
 192   </para>
 193  </refsect1>
 194
 195  <refsect1>
 196   <title>See Also</title>
 197
 198   <simplelist type="inline">
 199    <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
 200    <member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
 201    <member><xref linkend="sql-select" endterm="sql-select-title"></member>
 202    <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>
 203   </simplelist>
 204  </refsect1>
 205
 206 </refentry>
 207
 208 <!-- Keep this comment at the end of the file
 209 Local variables:
 210 mode: sgml
 211 sgml-omittag:nil
 212 sgml-shorttag:t
 213 sgml-minimize-attributes:nil
 214 sgml-always-quote-attributes:t
 215 sgml-indent-step:1
 216 sgml-indent-data:t
 217 sgml-parent-document:nil
 218 sgml-default-dtd-file:"../reference.ced"
 219 sgml-exposed-tags:nil
 220 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 221 sgml-local-ecat-files:nil
 222 End:
 223 -->