postgresql/doc/src/sgml/ref/create_table_as.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.28 2005/01/05 14:22:39 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATETABLEAS">
 <refmeta>
  <refentrytitle id="sql-createtableas-title">CREATE TABLE AS</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE TABLE AS</refname>
  <refpurpose>define a new table from the results of a query</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createtableas">
  <primary>CREATE TABLE AS</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
    AS <replaceable>query</replaceable>
</synopsis>
 </refsynopsisdiv>
  
 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE TABLE AS</command> creates a table and fills it
   with data computed by a <command>SELECT</command> command or an
   <command>EXECUTE</command> that runs a prepared
   <command>SELECT</command> command.  The table columns have the
   names and data types associated with the output columns of the
   <command>SELECT</command> (except that you can override the column
   names by giving an explicit list of new column names).
  </para>

  <para>
   <command>CREATE TABLE AS</command> bears some resemblance to
   creating a view, but it is really quite different: it creates a new
   table and evaluates the query just once to fill the new table
   initially.  The new table will not track subsequent changes to the
   source tables of the query.  In contrast, a view re-evaluates its
   defining <command>SELECT</command> statement whenever it is
   queried.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term>
    <listitem>
     <para>
      Ignored for compatibility. Refer to <xref
      linkend="sql-createtable" endterm="sql-createtable-title"> for
      details.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <variablelist>
   <varlistentry>
    <term><literal>TEMPORARY</> or <literal>TEMP</></term>
    <listitem>
     <para>
      If specified, the table is created as a temporary table.
      Refer to <xref linkend="sql-createtable" endterm="sql-createtable-title"> for details.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable>table_name</replaceable></term>
    <listitem>
     <para>
      The name (optionally schema-qualified) of the table to be created.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable>column_name</replaceable></term>
    <listitem>
     <para>
      The name of a column in the new table.  If column names are not
      provided, they are taken from the output column names of the
      query.  If the table is created from an
      <command>EXECUTE</command> command, a column name list cannot be
      specified.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>WITH OIDS</literal></term>
    <term><literal>WITHOUT OIDS</literal></term>
     <listitem>
      <para>
       This optional clause specifies whether the table created by
       <command>CREATE TABLE AS</command> should include OIDs. If
       neither form of this clause is specified, the value of the
       <xref linkend="guc-default-with-oids"> configuration parameter is
       used.
      </para>
     </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable>query</replaceable></term>
    <listitem>
     <para>
      A query statement (that is, a <command>SELECT</command> command
      or an <command>EXECUTE</command> command that runs a prepared
      <command>SELECT</command> command).  Refer to <xref
      linkend="sql-select" endterm="sql-select-title"> or <xref
      linkend="sql-execute" endterm="sql-execute-title">,
      respectively, for a description of the allowed syntax.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   This command is functionally similar to <xref
   linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is
   preferred since it is less likely to be confused with other uses of
   the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE
   TABLE AS</command> offers a superset of the functionality offered
   by <command>SELECT INTO</command>.
  </para>

  <para>
   Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
   TABLE AS</command> always included OIDs in the table it
   produced.  As of <productname>PostgresSQL</productname> 8.0,
   the <command>CREATE TABLE AS</command> command allows the user to
   explicitly specify whether OIDs should be included. If the
   presence of OIDs is not explicitly specified,
   the <xref linkend="guc-default-with-oids"> configuration variable is
   used. While this variable currently defaults to true, the default
   value may be changed in the future. Therefore, applications that
   require OIDs in the table created by <command>CREATE TABLE
   AS</command> should explicitly specify <literal>WITH
   OIDS</literal> to ensure compatibility with future versions
   of <productname>PostgreSQL</productname>.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>CREATE TABLE AS</command> is specified by the SQL:2003
   standard. There are some small differences between the definition
   of the command in SQL:2003 and its implementation in
   <productname>PostgreSQL</>:

   <itemizedlist spacing="compact">
    <listitem>
     <para>
      The standard requires parentheses around the subquery clause; in
      <productname>PostgreSQL</productname>, these parentheses are
      optional.
     </para>
    </listitem>

    <listitem>
     <para>
      The standard defines an <literal>ON COMMIT</literal> clause;
      this is not currently implemented by <productname>PostgreSQL</>.
     </para>
    </listitem>

    <listitem>
     <para>
      The standard defines a <literal>WITH DATA</literal> clause;
      this is not currently implemented by <productname>PostgreSQL</>.
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
   <member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
   <member><xref linkend="sql-select" endterm="sql-select-title"></member>
   <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>
  </simplelist>
 </refsect1>
 
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->