Skip to content

P
Postgres FD Implementation
Commit 40dc76e3 authored by Tom Lane's avatar Tom Lane
Browse files
Options

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.
parent 192d7245
Show whitespace changes
Inline Side-by-side
Showing with 113 additions and 62 deletions
doc/src/sgml/ref/create_table_as.sgml
View file @ 40dc76e3
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.5 2001/03/03 22:11:40 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.6 2001/03/20 20:54:41 tgl Exp $
Postgres documentation Postgres documentation
--> -->
...@@ -15,7 +15,7 @@ Postgres documentation ...@@ -15,7 +15,7 @@ Postgres documentation
CREATE TABLE AS CREATE TABLE AS
</refname> </refname>
<refpurpose> <refpurpose>
Creates a new table Creates a new table from the results of a SELECT
</refpurpose> </refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -41,7 +41,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab ...@@ -41,7 +41,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
<term>TEMPORARY or TEMP</term> <term>TEMPORARY or TEMP</term>
<listitem> <listitem>
<para> <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. automatically dropped on session exit.
Existing permanent tables with the same name are not visible Existing permanent tables with the same name are not visible
(in this session) while the temporary table exists. (in this session) while the temporary table exists.
...@@ -55,7 +55,10 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab ...@@ -55,7 +55,10 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
<term><replaceable>table</replaceable></term> <term><replaceable>table</replaceable></term>
<listitem> <listitem>
<para> <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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -76,8 +79,9 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab ...@@ -76,8 +79,9 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
<term><replaceable>select_clause</replaceable></term> <term><replaceable>select_clause</replaceable></term>
<listitem> <listitem>
<para> <para>
A valid query statement. Refer to SELECT for a description of the A valid query statement. Refer to
allowed syntax. <xref linkend="sql-select" endterm="sql-select-title">
for a description of the allowed syntax.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -92,27 +96,47 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab ...@@ -92,27 +96,47 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
<title> <title>
Outputs Outputs
</title> </title>
<para> <para>
Refer to <command>CREATE TABLE</command> Refer to
and <command>SELECT</command> for a summary of possible output <xref linkend="sql-createtable" endterm="sql-createtable-title">
messages. and
<xref linkend="sql-select" endterm="sql-select-title">
for a summary of possible output messages.
</para> </para>
</refsect2> </refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<refsect1info> <refsect1info>
<date>1998-09-22</date> <date>2001-03-20</date>
</refsect1info> </refsect1info>
<title> <title>
Description Description
</title> </title>
<para> <para>
<command>CREATE TABLE AS</command> enables a table to be created <command>CREATE TABLE AS</command> creates a table and fills it
from the contents of an existing table. with data computed by a <command>SELECT</command> command. The
It is functionally equivalent to 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">, <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> </para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/select.sgml
View file @ 40dc76e3
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.38 2001/02/04 12:18:08 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.39 2001/03/20 20:54:41 tgl Exp $
Postgres documentation Postgres documentation
--> -->
...@@ -15,7 +15,7 @@ Postgres documentation ...@@ -15,7 +15,7 @@ Postgres documentation
SELECT SELECT
</refname> </refname>
<refpurpose> <refpurpose>
Retrieve rows from a table or view. Retrieves rows from a table or view
</refpurpose></refnamediv> </refpurpose></refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <refsynopsisdivinfo>
...@@ -24,7 +24,6 @@ Postgres documentation ...@@ -24,7 +24,6 @@ Postgres documentation
<synopsis> <synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ] SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
* | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</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> [, ...] ] [ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="PARAMETER">condition</replaceable> ] [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
[ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ] [ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
...@@ -80,39 +79,6 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be: ...@@ -80,39 +79,6 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><replaceable class="PARAMETER">from_item</replaceable></term> <term><replaceable class="PARAMETER">from_item</replaceable></term>
<listitem> <listitem>
......
doc/src/sgml/ref/select_into.sgml
View file @ 40dc76e3
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.9 2001/01/13 23:58:55 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.10 2001/03/20 20:54:41 tgl Exp $
Postgres documentation Postgres documentation
--> -->
...@@ -15,7 +15,7 @@ Postgres documentation ...@@ -15,7 +15,7 @@ Postgres documentation
SELECT INTO SELECT INTO
</refname> </refname>
<refpurpose> <refpurpose>
Create a new table from an existing table or view Creates a new table from the results of a SELECT
</refpurpose></refnamediv> </refpurpose></refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <refsynopsisdivinfo>
...@@ -48,51 +48,112 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be: ...@@ -48,51 +48,112 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
<refsect2 id="R2-SQL-SELECTINTO-1"> <refsect2 id="R2-SQL-SELECTINTO-1">
<refsect2info> <refsect2info>
<date>1998-09-22</date> <date>2001-03-20</date>
</refsect2info> </refsect2info>
<title> <title>
Inputs Inputs
</title> </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> <para>
All input fields are described in detail for 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 other inputs are described in detail for
<xref linkend="sql-select" endterm="sql-select-title">. <xref linkend="sql-select" endterm="sql-select-title">.
</para> </para>
</refsect2> </refsect2>
<refsect2 id="R2-SQL-SELECTINTO-2"> <refsect2 id="R2-SQL-SELECTINTO-2">
<refsect2info> <refsect2info>
<date>1998-09-22</date> <date>2001-03-20</date>
</refsect2info> </refsect2info>
<title> <title>
Outputs Outputs
</title> </title>
<para> <para>
All output fields are described in detail for Refer to
<xref linkend="sql-select" endterm="sql-select-title">. <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> </para>
</refsect2> </refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-SELECTINTO-1"> <refsect1 id="R1-SQL-SELECTINTO-1">
<refsect1info> <refsect1info>
<date>1998-09-22</date> <date>2001-03-20</date>
</refsect1info> </refsect1info>
<title> <title>
Description Description
</title> </title>
<para> <para>
<command>SELECT INTO</command> creates a new table from the results <command>SELECT INTO</command> creates a new table and fills it
of a query. Typically, this with data computed by a query. The data is not returned to the
query draws data from an existing table, but any SQL query is allowed. 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> <note>
<para> <para>
<xref linkend="sql-createtableas" endterm="sql-createtableas-title"> <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> </para>
</note> </note>
</para> </para>
</refsect1> </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> </refentry>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment