Recommend CREATE TABLE AS in preference to SELECT INTO. Remove the

(inadequate anyway) mention of SELECT INTO from the main SELECT ref page.
Point out that SELECT INTO means something else in plpgsql and ecpg.

diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
index c9689bb3ea82b4d066f5f648e97993eb61fe1194..73f095dcd70f3e4d346a6f91103021db4a870b5e 100644 (file)
--- a/doc/src/sgml/ref/create_table_as.sgml
+++ b/doc/src/sgml/ref/create_table_as.sgml
@@ -15,7 +15,7 @@ Postgres documentation
    CREATE TABLE AS
   </refname>
   <refpurpose>
-   Creates a new table
+   Creates a new table from the results of a SELECT
   </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
@@ -41,7 +41,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
       <term>TEMPORARY or TEMP</term>
       <listitem>
        <para>
-       If specified, the table is created only for this session, and is
+       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.
@@ -55,7 +55,10 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
      <term><replaceable>table</replaceable></term>
      <listitem>
       <para>
-       The name of a new table to be created.
+        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>
@@ -76,8 +79,9 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
       <term><replaceable>select_clause</replaceable></term>
       <listitem>
        <para>
-       A valid query statement. Refer to SELECT for a description of the
-       allowed syntax.
+       A valid query statement. Refer to
+       <xref linkend="sql-select" endterm="sql-select-title">
+       for a description of the allowed syntax.
        </para>
       </listitem>
      </varlistentry>
@@ -92,27 +96,47 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
    <title>
     Outputs
    </title>
+
    <para>
-    Refer to <command>CREATE TABLE</command>
-    and <command>SELECT</command> for a summary of possible output
-    messages.
+    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>1998-09-22</date>
+   <date>2001-03-20</date>
   </refsect1info>
   <title>
    Description
   </title>
   <para>
-   <command>CREATE TABLE AS</command> enables a table to be created
-   from the contents of an existing table.
-   It is functionally equivalent to
+   <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 with perhaps a more direct syntax.
+   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>

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index be84e8a17ca1cea63269ad1be5f850a47e83c821..174cf4be35575cc4753dcd15807d8c0d5c7ec334 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -15,7 +15,7 @@ Postgres documentation
    SELECT
   </refname>
   <refpurpose>
-   Retrieve rows from a table or view.
+   Retrieves rows from a table or view
   </refpurpose></refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
@@ -24,7 +24,6 @@ Postgres documentation
   <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> [, ...] ]
@@ -80,39 +79,6 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
       </listitem>
      </varlistentry>
      
-    <varlistentry>
-     <term>TEMPORARY</term>
-     <term>TEMP</term>
-     <listitem>
-      <para>
-       If TEMPORARY or TEMP is specified,
-       the output table is created unique to this session, and is
-       automatically dropped on session exit.
-      </para>
-     </listitem>
-    </varlistentry>
-
-     <varlistentry>
-      <term><replaceable class="PARAMETER">new_table</replaceable></term>
-      <listitem>
-       <para>
-       If the INTO TABLE clause is specified, the result of the
-       query will be stored in a new table with the indicated
-       name, rather than being returned to the client.
-       The target table (<replaceable class="PARAMETER">new_table</replaceable>) will
-       be created automatically and must not exist before this command.
-        Refer to <command>SELECT INTO</command> for more information.
-
-       <note>
-        <para>
-         The <command>CREATE TABLE AS</command> statement will also
-         create a new  table from a SELECT query.
-        </para>
-       </note>
-       </para>
-      </listitem>
-     </varlistentry>
-     
      <varlistentry>
       <term><replaceable class="PARAMETER">from_item</replaceable></term>
       <listitem>

diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index b9eee2c49756dbce5e867fa66fba94e5f4afc6e1..d68be86a1bc52733d5d37accaaece8b158dbaf28 100644 (file)
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -15,7 +15,7 @@ Postgres documentation
    SELECT INTO
   </refname>
   <refpurpose>
-   Create a new table from an existing table or view
+   Creates a new table from the results of a SELECT
   </refpurpose></refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
@@ -48,51 +48,112 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
   
   <refsect2 id="R2-SQL-SELECTINTO-1">
    <refsect2info>
-    <date>1998-09-22</date>
+    <date>2001-03-20</date>
    </refsect2info>
    <title>
     Inputs
    </title>
+
+   <para>
+    <variablelist>
+    <varlistentry>
+     <term>TEMPORARY</term>
+     <term>TEMP</term>
+     <listitem>
+      <para>
+       If TEMPORARY or TEMP is specified,
+       the output 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 class="PARAMETER">new_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>
+    </variablelist>
+   </para>
+
    <para>
-    All input fields are described in detail for
+    All other inputs are described in detail for
     <xref linkend="sql-select" endterm="sql-select-title">.
    </para>
   </refsect2>
 
   <refsect2 id="R2-SQL-SELECTINTO-2">
    <refsect2info>
-    <date>1998-09-22</date>
+    <date>2001-03-20</date>
    </refsect2info>
    <title>
     Outputs
    </title>
+
    <para>
-    All output fields are described in detail for
-    <xref linkend="sql-select" endterm="sql-select-title">.
+    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 id="R1-SQL-SELECTINTO-1">
   <refsect1info>
-   <date>1998-09-22</date>
+   <date>2001-03-20</date>
   </refsect1info>
   <title>
    Description
   </title>
+
   <para>
-   <command>SELECT INTO</command> creates a new table from the results
-   of a query. Typically, this
-   query draws data from an existing table, but any SQL query is allowed.
+   <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 datatypes associated with the
+   output columns of the <command>SELECT</command>.
 
    <note>
     <para>
      <xref linkend="sql-createtableas" endterm="sql-createtableas-title">
-     is functionally equivalent to the <command>SELECT INTO</command> command.
+     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 PL/pgSQL or 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 PL/pgSQL and ecpg.
+    The <productname>Postgres</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