postgresql/doc/src/sgml/ref/select_into.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.19 2002/08/28 14:35:37 momjian Exp $
PostgreSQL documentation
-->

<refentry id="SQL-SELECTINTO">
 <refmeta>
  <refentrytitle id="SQL-SELECTINTO-TITLE">SELECT INTO</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   SELECT INTO
  </refname>
  <refpurpose>
   create a new table from the results of a query
  </refpurpose></refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>2000-12-11</date>
  </refsynopsisdivinfo>
  <synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
    * | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</replaceable> ] [, ...]
    INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable>
    [ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ]
    [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
    [ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
    [ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
    [ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ]
    [ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
    [ LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
    [ FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] ]

where <replaceable class="PARAMETER">from_item</replaceable> can be:

[ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ]
    [ [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ] ]
|
( <replaceable class="PARAMETER">select</replaceable> )
    [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ]
|
<replaceable class="PARAMETER">from_item</replaceable> [ NATURAL ] <replaceable class="PARAMETER">join_type</replaceable> <replaceable class="PARAMETER">from_item</replaceable>
    [ ON <replaceable class="PARAMETER">join_condition</replaceable> | USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ) ]
  </synopsis>
  
  <refsect2 id="R2-SQL-SELECTINTO-1">
   <refsect2info>
    <date>2001-03-20</date>
   </refsect2info>
   <title>
    Inputs
   </title>

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

     <varlistentry>
      <term><replaceable class="PARAMETER">new_table</replaceable></term>
      <listitem>
       <para>
        The name (optionally schema-qualified) of the table to be created.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    All other inputs are described in detail for
    <xref linkend="sql-select">.
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-SELECTINTO-2">
   <refsect2info>
    <date>2001-03-20</date>
   </refsect2info>
   <title>
    Outputs
   </title>

   <para>
    Refer to
    <xref linkend="sql-createtable">
    and
    <xref linkend="sql-select">
    for a summary of possible output messages.
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-SELECTINTO-1">
  <refsect1info>
   <date>2001-03-20</date>
  </refsect1info>
  <title>
   Description
  </title>

  <para>
   <command>SELECT INTO</command> creates a new table and fills it
   with data computed by a query.  The data is not returned to the
   client, as it is with a normal <command>SELECT</command>.  The new
   table's columns have the names and data types associated with the
   output columns of the <command>SELECT</command>.

   <note>
    <para>
     <xref linkend="sql-createtableas">
     is functionally equivalent to <command>SELECT INTO</command>.
     <command>CREATE TABLE AS</command> is the recommended syntax, since
     <command>SELECT INTO</command> is not standard.  In fact, this form of
     <command>SELECT INTO</command> is not available in <application>PL/pgSQL</application> or <xref linkend="app-ecpg">,
     because they interpret the INTO clause differently.
    </para>
   </note>
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-SELECTINTO-2">
  <title>
   Compatibility
  </title>

   <para>
    SQL92 uses <command>SELECT ... INTO</command> to represent selecting
    values into scalar variables of a host program, rather than creating
    a new table.  This indeed is the usage found in <application>PL/pgSQL</application> and <xref linkend="app-ecpg">.
    The <productname>PostgreSQL</productname> usage of <command>SELECT
    INTO</command> to represent table creation is historical.  It's best
    to use <command>CREATE TABLE AS</command> for this purpose in new code.
    (<command>CREATE TABLE AS</command> isn't standard either, but it's
    less likely to cause confusion.)
    </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:
-->