Skip to content

Commit 40dc76e

Browse files
tglsfdctglsfdc
committed
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.
1 parent 192d724 commit 40dc76e

File tree

3 files changed

+113
-62
lines changed

3 files changed

+113
-62
lines changed

‎doc/src/sgml/ref/create_table_as.sgml‎

Lines changed: 38 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.5 2001/03/03 22:11:40 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.6 2001/03/20 20:54:41 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -15,7 +15,7 @@ Postgres documentation
1515
CREATE TABLE AS
1616
</refname>
1717
<refpurpose>
18-
Creates a new table
18+
Creates a new table from the results of a SELECT
1919
</refpurpose>
2020
</refnamediv>
2121
<refsynopsisdiv>
@@ -41,7 +41,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
4141
<term>TEMPORARY or TEMP</term>
4242
<listitem>
4343
<para>
44-
If specified, the table is created only for this session, and is
44+
If specified, the table is created only within this session, and is
4545
automatically dropped on session exit.
4646
Existing permanent tables with the same name are not visible
4747
(in this session) while the temporary table exists.
@@ -55,7 +55,10 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
5555
<term><replaceable>table</replaceable></term>
5656
<listitem>
5757
<para>
58-
The name of a new table to be created.
58+
The name of the new table to be created.
59+
This table must not already exist. However, a temporary table
60+
can be created that has the same name as an existing permanent
61+
table.
5962
</para>
6063
</listitem>
6164
</varlistentry>
@@ -76,8 +79,9 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
7679
<term><replaceable>select_clause</replaceable></term>
7780
<listitem>
7881
<para>
79-
A valid query statement. Refer to SELECT for a description of the
80-
allowed syntax.
82+
A valid query statement. Refer to
83+
<xref linkend="sql-select" endterm="sql-select-title">
84+
for a description of the allowed syntax.
8185
</para>
8286
</listitem>
8387
</varlistentry>
@@ -92,27 +96,47 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable>table</replaceable> [ (<replaceab
9296
<title>
9397
Outputs
9498
</title>
99+
95100
<para>
96-
Refer to <command>CREATE TABLE</command>
97-
and <command>SELECT</command> for a summary of possible output
98-
messages.
101+
Refer to
102+
<xref linkend="sql-createtable" endterm="sql-createtable-title">
103+
and
104+
<xref linkend="sql-select" endterm="sql-select-title">
105+
for a summary of possible output messages.
99106
</para>
100107
</refsect2>
101108
</refsynopsisdiv>
102109

103110
<refsect1>
104111
<refsect1info>
105-
<date>1998-09-22</date>
112+
<date>2001-03-20</date>
106113
</refsect1info>
107114
<title>
108115
Description
109116
</title>
110117
<para>
111-
<command>CREATE TABLE AS</command> enables a table to be created
112-
from the contents of an existing table.
113-
It is functionally equivalent to
118+
<command>CREATE TABLE AS</command> creates a table and fills it
119+
with data computed by a <command>SELECT</command> command. The
120+
table columns have the names and datatypes associated with the
121+
output columns of the <command>SELECT</command> (except that you
122+
can override the <command>SELECT</command> column names by giving
123+
an explicit list of column names).
124+
</para>
125+
126+
<para>
127+
<command>CREATE TABLE AS</command> bears some resemblance to creating
128+
a view, but it is really quite different: it creates a new table and
129+
evaluates the <command>SELECT</command> just once to fill the new table
130+
initially. The new table will not track subsequent changes to
131+
the source tables of the <command>SELECT</command>. In contrast,
132+
a view re-evaluates the given <command>SELECT</command> whenever queried.
133+
</para>
134+
135+
<para>
136+
This command is functionally equivalent to
114137
<xref linkend="sql-selectinto" endterm="sql-selectinto-title">,
115-
but with perhaps a more direct syntax.
138+
but it is preferred since it is less likely to be confused with
139+
other uses of the <command>SELECT ... INTO</command> syntax.
116140
</para>
117141
</refsect1>
118142
</refentry>

‎doc/src/sgml/ref/select.sgml‎

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.38 2001/02/04 12:18:08 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.39 2001/03/20 20:54:41 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -15,7 +15,7 @@ Postgres documentation
1515
SELECT
1616
</refname>
1717
<refpurpose>
18-
Retrieve rows from a table or view.
18+
Retrieves rows from a table or view
1919
</refpurpose></refnamediv>
2020
<refsynopsisdiv>
2121
<refsynopsisdivinfo>
@@ -24,7 +24,6 @@ Postgres documentation
2424
<synopsis>
2525
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
2626
* | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</replaceable> ] [, ...]
27-
[ INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
2827
[ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ]
2928
[ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
3029
[ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
@@ -80,39 +79,6 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
8079
</listitem>
8180
</varlistentry>
8281

83-
<varlistentry>
84-
<term>TEMPORARY</term>
85-
<term>TEMP</term>
86-
<listitem>
87-
<para>
88-
If TEMPORARY or TEMP is specified,
89-
the output table is created unique to this session, and is
90-
automatically dropped on session exit.
91-
</para>
92-
</listitem>
93-
</varlistentry>
94-
95-
<varlistentry>
96-
<term><replaceable class="PARAMETER">new_table</replaceable></term>
97-
<listitem>
98-
<para>
99-
If the INTO TABLE clause is specified, the result of the
100-
query will be stored in a new table with the indicated
101-
name, rather than being returned to the client.
102-
The target table (<replaceable class="PARAMETER">new_table</replaceable>) will
103-
be created automatically and must not exist before this command.
104-
Refer to <command>SELECT INTO</command> for more information.
105-
106-
<note>
107-
<para>
108-
The <command>CREATE TABLE AS</command> statement will also
109-
create a new table from a SELECT query.
110-
</para>
111-
</note>
112-
</para>
113-
</listitem>
114-
</varlistentry>
115-
11682
<varlistentry>
11783
<term><replaceable class="PARAMETER">from_item</replaceable></term>
11884
<listitem>

‎doc/src/sgml/ref/select_into.sgml‎

Lines changed: 73 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.9 2001/01/13 23:58:55 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.10 2001/03/20 20:54:41 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -15,7 +15,7 @@ Postgres documentation
1515
SELECT INTO
1616
</refname>
1717
<refpurpose>
18-
Create a new table from an existing table or view
18+
Creates a new table from the results of a SELECT
1919
</refpurpose></refnamediv>
2020
<refsynopsisdiv>
2121
<refsynopsisdivinfo>
@@ -48,51 +48,112 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
4848

4949
<refsect2 id="R2-SQL-SELECTINTO-1">
5050
<refsect2info>
51-
<date>1998-09-22</date>
51+
<date>2001-03-20</date>
5252
</refsect2info>
5353
<title>
5454
Inputs
5555
</title>
56+
57+
<para>
58+
<variablelist>
59+
<varlistentry>
60+
<term>TEMPORARY</term>
61+
<term>TEMP</term>
62+
<listitem>
63+
<para>
64+
If TEMPORARY or TEMP is specified,
65+
the output table is created only within this session, and is
66+
automatically dropped on session exit.
67+
Existing permanent tables with the same name are not visible
68+
(in this session) while the temporary table exists.
69+
Any indexes created on a temporary table are automatically
70+
temporary as well.
71+
</para>
72+
</listitem>
73+
</varlistentry>
74+
75+
<varlistentry>
76+
<term><replaceable class="PARAMETER">new_table</replaceable></term>
77+
<listitem>
78+
<para>
79+
The name of the new table to be created.
80+
This table must not already exist. However, a temporary table
81+
can be created that has the same name as an existing permanent
82+
table.
83+
</para>
84+
</listitem>
85+
</varlistentry>
86+
</variablelist>
87+
</para>
88+
5689
<para>
57-
All input fields are described in detail for
90+
All other inputs are described in detail for
5891
<xref linkend="sql-select" endterm="sql-select-title">.
5992
</para>
6093
</refsect2>
6194

6295
<refsect2 id="R2-SQL-SELECTINTO-2">
6396
<refsect2info>
64-
<date>1998-09-22</date>
97+
<date>2001-03-20</date>
6598
</refsect2info>
6699
<title>
67100
Outputs
68101
</title>
102+
69103
<para>
70-
All output fields are described in detail for
71-
<xref linkend="sql-select" endterm="sql-select-title">.
104+
Refer to
105+
<xref linkend="sql-createtable" endterm="sql-createtable-title">
106+
and
107+
<xref linkend="sql-select" endterm="sql-select-title">
108+
for a summary of possible output messages.
72109
</para>
73110
</refsect2>
74111
</refsynopsisdiv>
75112

76113
<refsect1 id="R1-SQL-SELECTINTO-1">
77114
<refsect1info>
78-
<date>1998-09-22</date>
115+
<date>2001-03-20</date>
79116
</refsect1info>
80117
<title>
81118
Description
82119
</title>
120+
83121
<para>
84-
<command>SELECT INTO</command> creates a new table from the results
85-
of a query. Typically, this
86-
query draws data from an existing table, but any SQL query is allowed.
122+
<command>SELECT INTO</command> creates a new table and fills it
123+
with data computed by a query. The data is not returned to the
124+
client, as it is with a normal <command>SELECT</command>. The new
125+
table's columns have the names and datatypes associated with the
126+
output columns of the <command>SELECT</command>.
87127

88128
<note>
89129
<para>
90130
<xref linkend="sql-createtableas" endterm="sql-createtableas-title">
91-
is functionally equivalent to the <command>SELECT INTO</command> command.
131+
is functionally equivalent to <command>SELECT INTO</command>.
132+
<command>CREATE TABLE AS</command> is the recommended syntax, since
133+
<command>SELECT INTO</command> is not standard. In fact, this form of
134+
<command>SELECT INTO</command> is not available in PL/pgSQL or ecpg,
135+
because they interpret the INTO clause differently.
92136
</para>
93137
</note>
94138
</para>
95139
</refsect1>
140+
141+
<refsect1 id="R1-SQL-SELECTINTO-2">
142+
<title>
143+
Compatibility
144+
</title>
145+
146+
<para>
147+
SQL92 uses <command>SELECT ... INTO</command> to represent selecting
148+
values into scalar variables of a host program, rather than creating
149+
a new table. This indeed is the usage found in PL/pgSQL and ecpg.
150+
The <productname>Postgres</productname> usage of <command>SELECT
151+
INTO</command> to represent table creation is historical. It's best
152+
to use <command>CREATE TABLE AS</command> for this purpose in new code.
153+
(<command>CREATE TABLE AS</command> isn't standard either, but it's
154+
less likely to cause confusion.)
155+
</para>
156+
</refsect1>
96157
</refentry>
97158

98159
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)