1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/create_table_as.sgml
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="SQL-CREATETABLEAS">
|
1999-06-14 09:37:05 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>CREATE TABLE AS</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
1999-06-14 09:37:05 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2001-10-22 20:14:47 +02:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refnamediv>
|
2001-10-22 20:14:47 +02:00
|
|
|
<refname>CREATE TABLE AS</refname>
|
2004-08-24 02:06:51 +02:00
|
|
|
<refpurpose>define a new table from the results of a query</refpurpose>
|
1999-06-14 09:37:05 +02:00
|
|
|
</refnamediv>
|
2001-10-22 20:14:47 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createtableas">
|
|
|
|
<primary>CREATE TABLE AS</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refsynopsisdiv>
|
2001-10-22 20:14:47 +02:00
|
|
|
<synopsis>
|
2010-12-29 12:48:53 +01:00
|
|
|
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE <replaceable>table_name</replaceable>
|
2006-02-19 01:04:28 +01:00
|
|
|
[ (<replaceable>column_name</replaceable> [, ...] ) ]
|
2006-07-04 20:07:24 +02:00
|
|
|
[ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) | WITH OIDS | WITHOUT OIDS ]
|
2006-02-19 01:04:28 +01:00
|
|
|
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
|
|
|
|
[ TABLESPACE <replaceable class="PARAMETER">tablespace</replaceable> ]
|
2001-10-22 20:14:47 +02:00
|
|
|
AS <replaceable>query</replaceable>
|
2008-10-28 15:09:45 +01:00
|
|
|
[ WITH [ NO ] DATA ]
|
2003-04-22 12:08:08 +02:00
|
|
|
</synopsis>
|
1999-06-14 09:37:05 +02:00
|
|
|
</refsynopsisdiv>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refsect1>
|
2003-04-22 12:08:08 +02:00
|
|
|
<title>Description</title>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2001-03-20 21:54:41 +01:00
|
|
|
<command>CREATE TABLE AS</command> creates a table and fills it
|
2006-09-18 21:54:01 +02:00
|
|
|
with data computed by a <command>SELECT</command> command.
|
|
|
|
The table columns have the
|
2003-07-01 02:04:31 +02:00
|
|
|
names and data types associated with the output columns of the
|
|
|
|
<command>SELECT</command> (except that you can override the column
|
|
|
|
names by giving an explicit list of new column names).
|
2001-10-22 20:14:47 +02:00
|
|
|
</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 query just once to fill the new table
|
|
|
|
initially. The new table will not track subsequent changes to the
|
2002-04-23 04:07:16 +02:00
|
|
|
source tables of the query. In contrast, a view re-evaluates its
|
|
|
|
defining <command>SELECT</command> statement whenever it is
|
2001-10-22 20:14:47 +02:00
|
|
|
queried.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
2003-12-01 23:08:02 +01:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Ignored for compatibility. Refer to <xref
|
2010-04-03 09:23:02 +02:00
|
|
|
linkend="sql-createtable"> for
|
2003-12-01 23:08:02 +01:00
|
|
|
details.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
2001-10-22 20:14:47 +02:00
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2003-05-04 02:03:55 +02:00
|
|
|
<term><literal>TEMPORARY</> or <literal>TEMP</></term>
|
2001-10-22 20:14:47 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If specified, the table is created as a temporary table.
|
2010-04-03 09:23:02 +02:00
|
|
|
Refer to <xref linkend="sql-createtable"> for details.
|
2001-10-22 20:14:47 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-12-29 12:48:53 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><literal>UNLOGGED</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If specified, the table is created as an unlogged table.
|
|
|
|
Refer to <xref linkend="sql-createtable"> for details.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-10-22 20:14:47 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable>table_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-04-23 04:07:16 +02:00
|
|
|
The name (optionally schema-qualified) of the table to be created.
|
2001-10-22 20:14:47 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable>column_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The name of a column in the new table. If column names are not
|
2011-11-25 05:21:06 +01:00
|
|
|
provided, they are taken from the output column names of the query.
|
2001-10-22 20:14:47 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2004-01-11 00:28:45 +01:00
|
|
|
<varlistentry>
|
2006-07-04 20:07:24 +02:00
|
|
|
<term><literal>WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] )</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This clause specifies optional storage parameters for the new table;
|
|
|
|
see <xref linkend="sql-createtable-storage-parameters"
|
|
|
|
endterm="sql-createtable-storage-parameters-title"> for more
|
|
|
|
information. The <literal>WITH</> clause
|
|
|
|
can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>)
|
|
|
|
to specify that rows of the new table
|
|
|
|
should have OIDs (object identifiers) assigned to them, or
|
|
|
|
<literal>OIDS=FALSE</> to specify that the rows should not have OIDs.
|
2010-04-03 09:23:02 +02:00
|
|
|
See <xref linkend="sql-createtable"> for more information.
|
2006-07-04 20:07:24 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2004-01-11 00:28:45 +01:00
|
|
|
</varlistentry>
|
|
|
|
|
2006-07-02 04:23:23 +02:00
|
|
|
<varlistentry>
|
2006-07-04 20:07:24 +02:00
|
|
|
<term><literal>WITH OIDS</></term>
|
|
|
|
<term><literal>WITHOUT OIDS</></term>
|
2006-07-02 04:23:23 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2006-07-04 20:07:24 +02:00
|
|
|
These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</>
|
|
|
|
and <literal>WITH (OIDS=FALSE)</>, respectively. If you wish to give
|
|
|
|
both an <literal>OIDS</> setting and storage parameters, you must use
|
|
|
|
the <literal>WITH ( ... )</> syntax; see above.
|
2006-07-02 04:23:23 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2006-02-19 01:04:28 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><literal>ON COMMIT</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The behavior of temporary tables at the end of a transaction
|
|
|
|
block can be controlled using <literal>ON COMMIT</literal>.
|
|
|
|
The three options are:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>PRESERVE ROWS</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
No special action is taken at the ends of transactions.
|
|
|
|
This is the default behavior.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>DELETE ROWS</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
All rows in the temporary table will be deleted at the end
|
|
|
|
of each transaction block. Essentially, an automatic <xref
|
2010-04-03 09:23:02 +02:00
|
|
|
linkend="sql-truncate"> is done
|
2006-02-19 01:04:28 +01:00
|
|
|
at each commit.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>DROP</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The temporary table will be dropped at the end of the current
|
|
|
|
transaction block.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2011-08-07 09:49:45 +02:00
|
|
|
</variablelist></para>
|
2006-02-19 01:04:28 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>TABLESPACE <replaceable class="PARAMETER">tablespace</replaceable></literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The <replaceable class="PARAMETER">tablespace</replaceable> is the name
|
|
|
|
of the tablespace in which the new table is to be created.
|
|
|
|
If not specified,
|
2007-06-03 19:08:34 +02:00
|
|
|
<xref linkend="guc-default-tablespace"> is consulted, or
|
|
|
|
<xref linkend="guc-temp-tablespaces"> if the table is temporary.
|
2006-02-19 01:04:28 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-10-22 20:14:47 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable>query</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2011-08-30 19:32:49 +02:00
|
|
|
A <xref linkend="sql-select">, <link
|
|
|
|
linkend="sql-table">TABLE</link>, or <xref linkend="sql-values">
|
|
|
|
command, or an <xref linkend="sql-execute"> command that runs a
|
|
|
|
prepared <command>SELECT</>, <command>TABLE</>, or
|
|
|
|
<command>VALUES</> query.
|
2001-10-22 20:14:47 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2008-10-28 15:09:45 +01:00
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>WITH [ NO ] DATA</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This clause specifies whether or not the data produced by the query
|
|
|
|
should be copied into the new table. If not, only the table structure
|
|
|
|
is copied. The default is to copy the data.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-10-22 20:14:47 +02:00
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
2003-12-01 23:08:02 +01:00
|
|
|
This command is functionally similar to <xref
|
2010-04-03 09:23:02 +02:00
|
|
|
linkend="sql-selectinto">, but it is
|
2003-12-01 23:08:02 +01:00
|
|
|
preferred since it is less likely to be confused with other uses of
|
2004-01-11 00:28:45 +01:00
|
|
|
the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE
|
2004-12-13 19:05:10 +01:00
|
|
|
TABLE AS</command> offers a superset of the functionality offered
|
2004-01-11 00:28:45 +01:00
|
|
|
by <command>SELECT INTO</command>.
|
2003-12-01 23:08:02 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2004-08-04 23:34:35 +02:00
|
|
|
Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
|
2004-01-11 00:28:45 +01:00
|
|
|
TABLE AS</command> always included OIDs in the table it
|
2005-11-01 22:09:51 +01:00
|
|
|
created. As of <productname>PostgreSQL</productname> 8.0,
|
2004-01-11 00:28:45 +01:00
|
|
|
the <command>CREATE TABLE AS</command> command allows the user to
|
2004-12-13 19:05:10 +01:00
|
|
|
explicitly specify whether OIDs should be included. If the
|
|
|
|
presence of OIDs is not explicitly specified,
|
2004-03-09 17:57:47 +01:00
|
|
|
the <xref linkend="guc-default-with-oids"> configuration variable is
|
2005-11-01 22:09:51 +01:00
|
|
|
used. As of <productname>PostgreSQL</productname> 8.1,
|
|
|
|
this variable is false by default, so the default behavior is not
|
|
|
|
identical to pre-8.0 releases. Applications that
|
2004-01-11 00:28:45 +01:00
|
|
|
require OIDs in the table created by <command>CREATE TABLE
|
2006-07-04 20:07:24 +02:00
|
|
|
AS</command> should explicitly specify <literal>WITH (OIDS)</literal>
|
2011-11-25 05:21:06 +01:00
|
|
|
to ensure desired behavior.
|
2001-03-20 21:54:41 +01:00
|
|
|
</para>
|
2001-10-22 20:14:47 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2005-01-09 06:57:45 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Create a new table <literal>films_recent</literal> consisting of only
|
|
|
|
recent entries from the table <literal>films</literal>:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE films_recent AS
|
|
|
|
SELECT * FROM films WHERE date_prod >= '2002-01-01';
|
2006-02-19 01:04:28 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2008-11-20 15:04:46 +01:00
|
|
|
<para>
|
|
|
|
To copy a table completely, the short form using
|
|
|
|
the <literal>TABLE</literal> command can also be used:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE films2 AS
|
|
|
|
TABLE films;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2006-02-19 01:04:28 +01:00
|
|
|
<para>
|
2006-07-04 20:07:24 +02:00
|
|
|
Create a new temporary table <literal>films_recent</literal>, consisting of
|
|
|
|
only recent entries from the table <literal>films</literal>, using a
|
|
|
|
prepared statement. The new table has OIDs and will be dropped at commit:
|
2006-02-19 01:04:28 +01:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
PREPARE recentfilms(date) AS
|
|
|
|
SELECT * FROM films WHERE date_prod > $1;
|
2006-07-04 20:07:24 +02:00
|
|
|
CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS
|
2006-02-19 01:04:28 +01:00
|
|
|
EXECUTE recentfilms('2002-01-01');
|
2011-08-07 09:49:45 +02:00
|
|
|
</programlisting></para>
|
2005-01-09 06:57:45 +01:00
|
|
|
</refsect1>
|
|
|
|
|
2001-10-22 20:14:47 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
2001-03-20 21:54:41 +01:00
|
|
|
|
|
|
|
<para>
|
2005-11-01 22:09:51 +01:00
|
|
|
<command>CREATE TABLE AS</command> conforms to the <acronym>SQL</acronym>
|
2008-10-28 15:09:45 +01:00
|
|
|
standard. The following are nonstandard extensions:
|
2004-09-23 05:43:57 +02:00
|
|
|
|
|
|
|
<itemizedlist spacing="compact">
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The standard requires parentheses around the subquery clause; in
|
|
|
|
<productname>PostgreSQL</productname>, these parentheses are
|
|
|
|
optional.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2008-10-28 15:09:45 +01:00
|
|
|
In the standard, the <literal>WITH [ NO ] DATA</literal> clause
|
|
|
|
is required; in PostgreSQL it is optional.
|
2005-11-01 22:09:51 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
2011-08-07 09:49:45 +02:00
|
|
|
<para><productname>PostgreSQL</> handles temporary tables in a way
|
2006-07-04 20:07:24 +02:00
|
|
|
rather different from the standard; see
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-createtable">
|
2006-07-04 20:07:24 +02:00
|
|
|
for details.
|
2005-11-01 22:09:51 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2006-07-04 20:07:24 +02:00
|
|
|
The <literal>WITH</> clause is a <productname>PostgreSQL</productname>
|
|
|
|
extension; neither storage parameters nor OIDs are in the standard.
|
2004-09-23 05:43:57 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2006-02-19 01:04:28 +01:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The <productname>PostgreSQL</productname> concept of tablespaces is not
|
|
|
|
part of the standard. Hence, the clause <literal>TABLESPACE</literal>
|
|
|
|
is an extension.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2011-08-07 09:49:45 +02:00
|
|
|
</itemizedlist></para>
|
2001-10-22 20:14:47 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2010-04-03 09:23:02 +02:00
|
|
|
<member><xref linkend="sql-createtable"></member>
|
|
|
|
<member><xref linkend="sql-execute"></member>
|
|
|
|
<member><xref linkend="sql-select"></member>
|
|
|
|
<member><xref linkend="sql-selectinto"></member>
|
|
|
|
<member><xref linkend="sql-values"></member>
|
2001-10-22 20:14:47 +02:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
</refentry>
|