begriffs open source - ai-pg/blob - full-docs/man7/CREATE_TABLE_AS.7

   1 '\" t
   2 .\"     Title: CREATE TABLE AS
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE TABLE AS" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_TABLE_AS \- define a new table from the results of a query
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] \fItable_name\fR
  36     [ (\fIcolumn_name\fR [, \&.\&.\&.] ) ]
  37     [ USING \fImethod\fR ]
  38     [ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) | WITHOUT OIDS ]
  39     [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
  40     [ TABLESPACE \fItablespace_name\fR ]
  41     AS \fIquery\fR
  42     [ WITH [ NO ] DATA ]
  43 .fi
  44 .SH "DESCRIPTION"
  45 .PP
  46 \fBCREATE TABLE AS\fR
  47 creates a table and fills it with data computed by a
  48 \fBSELECT\fR
  49 command\&. The table columns have the names and data types associated with the output columns of the
  50 \fBSELECT\fR
  51 (except that you can override the column names by giving an explicit list of new column names)\&.
  52 .PP
  53 \fBCREATE TABLE AS\fR
  54 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 source tables of the query\&. In contrast, a view re\-evaluates its defining
  55 \fBSELECT\fR
  56 statement whenever it is queried\&.
  57 .PP
  58 \fBCREATE TABLE AS\fR
  59 requires
  60 CREATE
  61 privilege on the schema used for the table\&.
  62 .SH "PARAMETERS"
  63 .PP
  64 GLOBAL or LOCAL
  65 .RS 4
  66 Ignored for compatibility\&. Use of these keywords is deprecated; refer to
  67 CREATE TABLE (\fBCREATE_TABLE\fR(7))
  68 for details\&.
  69 .RE
  70 .PP
  71 TEMPORARY or TEMP
  72 .RS 4
  73 If specified, the table is created as a temporary table\&. Refer to
  74 CREATE TABLE (\fBCREATE_TABLE\fR(7))
  75 for details\&.
  76 .RE
  77 .PP
  78 UNLOGGED
  79 .RS 4
  80 If specified, the table is created as an unlogged table\&. Refer to
  81 CREATE TABLE (\fBCREATE_TABLE\fR(7))
  82 for details\&.
  83 .RE
  84 .PP
  85 IF NOT EXISTS
  86 .RS 4
  87 Do not throw an error if a relation with the same name already exists; simply issue a notice and leave the table unmodified\&.
  88 .RE
  89 .PP
  90 \fItable_name\fR
  91 .RS 4
  92 The name (optionally schema\-qualified) of the table to be created\&.
  93 .RE
  94 .PP
  95 \fIcolumn_name\fR
  96 .RS 4
  97 The name of a column in the new table\&. If column names are not provided, they are taken from the output column names of the query\&.
  98 .RE
  99 .PP
 100 USING \fImethod\fR
 101 .RS 4
 102 This optional clause specifies the table access method to use to store the contents for the new table; the method needs be an access method of type
 103 TABLE\&. See
 104 Chapter\ \&62
 105 for more information\&. If this option is not specified, the default table access method is chosen for the new table\&. See
 106 default_table_access_method
 107 for more information\&.
 108 .RE
 109 .PP
 110 WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
 111 .RS 4
 112 This clause specifies optional storage parameters for the new table; see
 113 Storage Parameters
 114 in the
 115 CREATE TABLE (\fBCREATE_TABLE\fR(7))
 116 documentation for more information\&. For backward\-compatibility the
 117 WITH
 118 clause for a table can also include
 119 OIDS=FALSE
 120 to specify that rows of the new table should contain no OIDs (object identifiers),
 121 OIDS=TRUE
 122 is not supported anymore\&.
 123 .RE
 124 .PP
 125 WITHOUT OIDS
 126 .RS 4
 127 This is backward\-compatible syntax for declaring a table
 128 WITHOUT OIDS, creating a table
 129 WITH OIDS
 130 is not supported anymore\&.
 131 .RE
 132 .PP
 133 ON COMMIT
 134 .RS 4
 135 The behavior of temporary tables at the end of a transaction block can be controlled using
 136 ON COMMIT\&. The three options are:
 137 .PP
 138 PRESERVE ROWS
 139 .RS 4
 140 No special action is taken at the ends of transactions\&. This is the default behavior\&.
 141 .RE
 142 .PP
 143 DELETE ROWS
 144 .RS 4
 145 All rows in the temporary table will be deleted at the end of each transaction block\&. Essentially, an automatic
 146 \fBTRUNCATE\fR
 147 is done at each commit\&.
 148 .RE
 149 .PP
 150 DROP
 151 .RS 4
 152 The temporary table will be dropped at the end of the current transaction block\&.
 153 .RE
 154 .RE
 155 .PP
 156 TABLESPACE \fItablespace_name\fR
 157 .RS 4
 158 The
 159 \fItablespace_name\fR
 160 is the name of the tablespace in which the new table is to be created\&. If not specified,
 161 default_tablespace
 162 is consulted, or
 163 temp_tablespaces
 164 if the table is temporary\&.
 165 .RE
 166 .PP
 167 \fIquery\fR
 168 .RS 4
 169 A
 170 \fBSELECT\fR,
 171 \fBTABLE\fR, or
 172 \fBVALUES\fR
 173 command, or an
 174 \fBEXECUTE\fR
 175 command that runs a prepared
 176 \fBSELECT\fR,
 177 \fBTABLE\fR, or
 178 \fBVALUES\fR
 179 query\&.
 180 .RE
 181 .PP
 182 WITH [ NO ] DATA
 183 .RS 4
 184 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\&.
 185 .RE
 186 .SH "NOTES"
 187 .PP
 188 This command is functionally similar to
 189 SELECT INTO (\fBSELECT_INTO\fR(7)), but it is preferred since it is less likely to be confused with other uses of the
 190 \fBSELECT INTO\fR
 191 syntax\&. Furthermore,
 192 \fBCREATE TABLE AS\fR
 193 offers a superset of the functionality offered by
 194 \fBSELECT INTO\fR\&.
 195 .SH "EXAMPLES"
 196 .PP
 197 Create a new table
 198 films_recent
 199 consisting of only recent entries from the table
 200 films:
 201 .sp
 202 .if n \{\
 203 .RS 4
 204 .\}
 205 .nf
 206 CREATE TABLE films_recent AS
 207   SELECT * FROM films WHERE date_prod >= \*(Aq2002\-01\-01\*(Aq;
 208 .fi
 209 .if n \{\
 210 .RE
 211 .\}
 212 .PP
 213 To copy a table completely, the short form using the
 214 TABLE
 215 command can also be used:
 216 .sp
 217 .if n \{\
 218 .RS 4
 219 .\}
 220 .nf
 221 CREATE TABLE films2 AS
 222   TABLE films;
 223 .fi
 224 .if n \{\
 225 .RE
 226 .\}
 227 .PP
 228 Create a new temporary table
 229 films_recent, consisting of only recent entries from the table
 230 films, using a prepared statement\&. The new table will be dropped at commit:
 231 .sp
 232 .if n \{\
 233 .RS 4
 234 .\}
 235 .nf
 236 PREPARE recentfilms(date) AS
 237   SELECT * FROM films WHERE date_prod > $1;
 238 CREATE TEMP TABLE films_recent ON COMMIT DROP AS
 239   EXECUTE recentfilms(\*(Aq2002\-01\-01\*(Aq);
 240 .fi
 241 .if n \{\
 242 .RE
 243 .\}
 244 .SH "COMPATIBILITY"
 245 .PP
 246 \fBCREATE TABLE AS\fR
 247 conforms to the
 248 SQL
 249 standard\&. The following are nonstandard extensions:
 250 .sp
 251 .RS 4
 252 .ie n \{\
 253 \h'-04'\(bu\h'+03'\c
 254 .\}
 255 .el \{\
 256 .sp -1
 257 .IP \(bu 2.3
 258 .\}
 259 The standard requires parentheses around the subquery clause; in
 260 PostgreSQL, these parentheses are optional\&.
 261 .RE
 262 .sp
 263 .RS 4
 264 .ie n \{\
 265 \h'-04'\(bu\h'+03'\c
 266 .\}
 267 .el \{\
 268 .sp -1
 269 .IP \(bu 2.3
 270 .\}
 271 In the standard, the
 272 WITH [ NO ] DATA
 273 clause is required; in PostgreSQL it is optional\&.
 274 .RE
 275 .sp
 276 .RS 4
 277 .ie n \{\
 278 \h'-04'\(bu\h'+03'\c
 279 .\}
 280 .el \{\
 281 .sp -1
 282 .IP \(bu 2.3
 283 .\}
 284 PostgreSQL
 285 handles temporary tables in a way rather different from the standard; see
 286 CREATE TABLE (\fBCREATE_TABLE\fR(7))
 287 for details\&.
 288 .RE
 289 .sp
 290 .RS 4
 291 .ie n \{\
 292 \h'-04'\(bu\h'+03'\c
 293 .\}
 294 .el \{\
 295 .sp -1
 296 .IP \(bu 2.3
 297 .\}
 298 The
 299 WITH
 300 clause is a
 301 PostgreSQL
 302 extension; storage parameters are not in the standard\&.
 303 .RE
 304 .sp
 305 .RS 4
 306 .ie n \{\
 307 \h'-04'\(bu\h'+03'\c
 308 .\}
 309 .el \{\
 310 .sp -1
 311 .IP \(bu 2.3
 312 .\}
 313 The
 314 PostgreSQL
 315 concept of tablespaces is not part of the standard\&. Hence, the clause
 316 TABLESPACE
 317 is an extension\&.
 318 .RE
 319 .SH "SEE ALSO"
 320 CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)), \fBEXECUTE\fR(7), \fBSELECT\fR(7), SELECT INTO (\fBSELECT_INTO\fR(7)), \fBVALUES\fR(7)