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

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.7 2001/09/03 12:57:49 petere Exp $
Postgres 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>
   create a new table from the results of a query
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>2001-03-03</date>
  </refsynopsisdivinfo>
  <synopsis>
CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceable>column</replaceable> [, ...] ) ]
     AS <replaceable>select_clause</replaceable>
  </synopsis>
  
  <refsect2>
   <refsect2info>
    <date>1998-09-22</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
   
   <variablelist>
     <varlistentry>
      <term>TEMPORARY or TEMP</term>
      <listitem>
       <para>
	If specified, the table is created only within this session, and is
	automatically dropped on session exit.
	Existing permanent tables with the same name are not visible
	(in this session) while the temporary table exists.
	Any indexes created on a temporary table are automatically
	temporary as well.
       </para>
      </listitem>
     </varlistentry>

    <varlistentry>
     <term><replaceable>table</replaceable></term>
     <listitem>
      <para>
        The name of the new table to be created.
	This table must not already exist.  However, a temporary table
	can be created that has the same name as an existing permanent
	table.
      </para>
     </listitem>
    </varlistentry>

     <varlistentry>
      <term><replaceable>column</replaceable></term>
      <listitem>
       <para>
	The name of a column. Multiple column names can be specified using
	a comma-delimited list of column names.  If column names are not
	provided, they are taken from the output column names of the
	SELECT query.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable>select_clause</replaceable></term>
      <listitem>
       <para>
	A valid query statement. Refer to
	<xref linkend="sql-select" endterm="sql-select-title">
	for a description of the allowed syntax.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2>
   <refsect2info>
    <date>1998-09-22</date>
   </refsect2info>
   <title>
    Outputs
   </title>

   <para>
    Refer to
    <xref linkend="sql-createtable" endterm="sql-createtable-title">
    and
    <xref linkend="sql-select" endterm="sql-select-title">
    for a summary of possible output messages.
   </para>
  </refsect2>
 </refsynopsisdiv>
 
 <refsect1>
  <refsect1info>
   <date>2001-03-20</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>CREATE TABLE AS</command> creates a table and fills it
   with data computed by a <command>SELECT</command> command.  The
   table columns have the names and datatypes associated with the
   output columns of the <command>SELECT</command> (except that you
   can override the <command>SELECT</command> column names by giving
   an explicit list of 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 <command>SELECT</command> just once to fill the new table
   initially.  The new table will not track subsequent changes to
   the source tables of the <command>SELECT</command>.  In contrast,
   a view re-evaluates the given <command>SELECT</command> whenever queried.
  </para>

  <para>
   This command is functionally equivalent 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</command> syntax.
  </para>
 </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:
-->