begriffs open source - ai-pg/blob - full-docs/txt/sql-createtableas.txt

   1
   2 CREATE TABLE AS
   3
   4    CREATE TABLE AS — define a new table from the results of a query
   5
   6 Synopsis
   7
   8 CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
   9 STS ] table_name
  10     [ (column_name [, ...] ) ]
  11     [ USING method ]
  12     [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ]
  13     [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
  14     [ TABLESPACE tablespace_name ]
  15     AS query
  16     [ WITH [ NO ] DATA ]
  17
  18 Description
  19
  20    CREATE TABLE AS creates a table and fills it with data computed by a
  21    SELECT command. The table columns have the names and data types
  22    associated with the output columns of the SELECT (except that you can
  23    override the column names by giving an explicit list of new column
  24    names).
  25
  26    CREATE TABLE AS bears some resemblance to creating a view, but it is
  27    really quite different: it creates a new table and evaluates the query
  28    just once to fill the new table initially. The new table will not track
  29    subsequent changes to the source tables of the query. In contrast, a
  30    view re-evaluates its defining SELECT statement whenever it is queried.
  31
  32    CREATE TABLE AS requires CREATE privilege on the schema used for the
  33    table.
  34
  35 Parameters
  36
  37    GLOBAL or LOCAL
  38           Ignored for compatibility. Use of these keywords is deprecated;
  39           refer to CREATE TABLE for details.
  40
  41    TEMPORARY or TEMP
  42           If specified, the table is created as a temporary table. Refer
  43           to CREATE TABLE for details.
  44
  45    UNLOGGED
  46           If specified, the table is created as an unlogged table. Refer
  47           to CREATE TABLE for details.
  48
  49    IF NOT EXISTS
  50           Do not throw an error if a relation with the same name already
  51           exists; simply issue a notice and leave the table unmodified.
  52
  53    table_name
  54           The name (optionally schema-qualified) of the table to be
  55           created.
  56
  57    column_name
  58           The name of a column in the new table. If column names are not
  59           provided, they are taken from the output column names of the
  60           query.
  61
  62    USING method
  63           This optional clause specifies the table access method to use to
  64           store the contents for the new table; the method needs be an
  65           access method of type TABLE. See Chapter 62 for more
  66           information. If this option is not specified, the default table
  67           access method is chosen for the new table. See
  68           default_table_access_method for more information.
  69
  70    WITH ( storage_parameter [= value] [, ... ] )
  71           This clause specifies optional storage parameters for the new
  72           table; see Storage Parameters in the CREATE TABLE documentation
  73           for more information. For backward-compatibility the WITH clause
  74           for a table can also include OIDS=FALSE to specify that rows of
  75           the new table should contain no OIDs (object identifiers),
  76           OIDS=TRUE is not supported anymore.
  77
  78    WITHOUT OIDS
  79           This is backward-compatible syntax for declaring a table WITHOUT
  80           OIDS, creating a table WITH OIDS is not supported anymore.
  81
  82    ON COMMIT
  83           The behavior of temporary tables at the end of a transaction
  84           block can be controlled using ON COMMIT. The three options are:
  85
  86         PRESERVE ROWS
  87                 No special action is taken at the ends of transactions.
  88                 This is the default behavior.
  89
  90         DELETE ROWS
  91                 All rows in the temporary table will be deleted at the end
  92                 of each transaction block. Essentially, an automatic
  93                 TRUNCATE is done at each commit.
  94
  95         DROP
  96                 The temporary table will be dropped at the end of the
  97                 current transaction block.
  98
  99    TABLESPACE tablespace_name
 100           The tablespace_name is the name of the tablespace in which the
 101           new table is to be created. If not specified, default_tablespace
 102           is consulted, or temp_tablespaces if the table is temporary.
 103
 104    query
 105           A SELECT, TABLE, or VALUES command, or an EXECUTE command that
 106           runs a prepared SELECT, TABLE, or VALUES query.
 107
 108    WITH [ NO ] DATA
 109           This clause specifies whether or not the data produced by the
 110           query should be copied into the new table. If not, only the
 111           table structure is copied. The default is to copy the data.
 112
 113 Notes
 114
 115    This command is functionally similar to SELECT INTO, but it is
 116    preferred since it is less likely to be confused with other uses of the
 117    SELECT INTO syntax. Furthermore, CREATE TABLE AS offers a superset of
 118    the functionality offered by SELECT INTO.
 119
 120 Examples
 121
 122    Create a new table films_recent consisting of only recent entries from
 123    the table films:
 124 CREATE TABLE films_recent AS
 125   SELECT * FROM films WHERE date_prod >= '2002-01-01';
 126
 127    To copy a table completely, the short form using the TABLE command can
 128    also be used:
 129 CREATE TABLE films2 AS
 130   TABLE films;
 131
 132    Create a new temporary table films_recent, consisting of only recent
 133    entries from the table films, using a prepared statement. The new table
 134    will be dropped at commit:
 135 PREPARE recentfilms(date) AS
 136   SELECT * FROM films WHERE date_prod > $1;
 137 CREATE TEMP TABLE films_recent ON COMMIT DROP AS
 138   EXECUTE recentfilms('2002-01-01');
 139
 140 Compatibility
 141
 142    CREATE TABLE AS conforms to the SQL standard. The following are
 143    nonstandard extensions:
 144      * The standard requires parentheses around the subquery clause; in
 145        PostgreSQL, these parentheses are optional.
 146      * In the standard, the WITH [ NO ] DATA clause is required; in
 147        PostgreSQL it is optional.
 148      * PostgreSQL handles temporary tables in a way rather different from
 149        the standard; see CREATE TABLE for details.
 150      * The WITH clause is a PostgreSQL extension; storage parameters are
 151        not in the standard.
 152      * The PostgreSQL concept of tablespaces is not part of the standard.
 153        Hence, the clause TABLESPACE is an extension.
 154
 155 See Also
 156
 157    CREATE MATERIALIZED VIEW, CREATE TABLE, EXECUTE, SELECT, SELECT INTO,
 158    VALUES