~ubuntu-branches/debian/experimental/postgresql-11/experimental

« back to all changes in this revision

Viewing changes to doc/src/sgml/man7/INSERT.7

  • Committer: Package Import Robot
  • Author(s): Christoph Berg
  • Date: 2018-05-22 14:19:08 UTC
  • Revision ID: package-import@ubuntu.com-20180522141908-0oy9ujs1b5vrda74
Tags: upstream-11~beta1
ImportĀ upstreamĀ versionĀ 11~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
'\" t
 
2
.\"     Title: INSERT
 
3
.\"    Author: The PostgreSQL Global Development Group
 
4
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
 
5
.\"      Date: 2018
 
6
.\"    Manual: PostgreSQL 11beta1 Documentation
 
7
.\"    Source: PostgreSQL 11beta1
 
8
.\"  Language: English
 
9
.\"
 
10
.TH "INSERT" "7" "2018" "PostgreSQL 11beta1" "PostgreSQL 11beta1 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
INSERT \- create new rows in a table
 
32
.SH "SYNOPSIS"
 
33
.sp
 
34
.nf
 
35
[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ]
 
36
INSERT INTO \fItable_name\fR [ AS \fIalias\fR ] [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ]
 
37
    [ OVERRIDING { SYSTEM | USER} VALUE ]
 
38
    { DEFAULT VALUES | VALUES ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) [, \&.\&.\&.] | \fIquery\fR }
 
39
    [ ON CONFLICT [ \fIconflict_target\fR ] \fIconflict_action\fR ]
 
40
    [ RETURNING * | \fIoutput_expression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] ]
 
41
 
 
42
where \fIconflict_target\fR can be one of:
 
43
 
 
44
    ( { \fIindex_column_name\fR | ( \fIindex_expression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR ] [, \&.\&.\&.] ) [ WHERE \fIindex_predicate\fR ]
 
45
    ON CONSTRAINT \fIconstraint_name\fR
 
46
 
 
47
and \fIconflict_action\fR is one of:
 
48
 
 
49
    DO NOTHING
 
50
    DO UPDATE SET { \fIcolumn_name\fR = { \fIexpression\fR | DEFAULT } |
 
51
                    ( \fIcolumn_name\fR [, \&.\&.\&.] ) = [ ROW ] ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) |
 
52
                    ( \fIcolumn_name\fR [, \&.\&.\&.] ) = ( \fIsub\-SELECT\fR )
 
53
                  } [, \&.\&.\&.]
 
54
              [ WHERE \fIcondition\fR ]
 
55
.fi
 
56
.SH "DESCRIPTION"
 
57
.PP
 
58
\fBINSERT\fR
 
59
inserts new rows into a table\&. One can insert one or more rows specified by value expressions, or zero or more rows resulting from a query\&.
 
60
.PP
 
61
The target column names can be listed in any order\&. If no list of column names is given at all, the default is all the columns of the table in their declared order; or the first
 
62
\fIN\fR
 
63
column names, if there are only
 
64
\fIN\fR
 
65
columns supplied by the
 
66
VALUES
 
67
clause or
 
68
\fIquery\fR\&. The values supplied by the
 
69
VALUES
 
70
clause or
 
71
\fIquery\fR
 
72
are associated with the explicit or implicit column list left\-to\-right\&.
 
73
.PP
 
74
Each column not present in the explicit or implicit column list will be filled with a default value, either its declared default value or null if there is none\&.
 
75
.PP
 
76
If the expression for any column is not of the correct data type, automatic type conversion will be attempted\&.
 
77
.PP
 
78
ON CONFLICT
 
79
can be used to specify an alternative action to raising a unique constraint or exclusion constraint violation error\&. (See
 
80
ON CONFLICT Clause
 
81
below\&.)
 
82
.PP
 
83
The optional
 
84
RETURNING
 
85
clause causes
 
86
\fBINSERT\fR
 
87
to compute and return value(s) based on each row actually inserted (or updated, if an
 
88
ON CONFLICT DO UPDATE
 
89
clause was used)\&. This is primarily useful for obtaining values that were supplied by defaults, such as a serial sequence number\&. However, any expression using the table\*(Aqs columns is allowed\&. The syntax of the
 
90
RETURNING
 
91
list is identical to that of the output list of
 
92
\fBSELECT\fR\&. Only rows that were successfully inserted or updated will be returned\&. For example, if a row was locked but not updated because an
 
93
ON CONFLICT DO UPDATE \&.\&.\&. WHERE
 
94
clause
 
95
\fIcondition\fR
 
96
was not satisfied, the row will not be returned\&.
 
97
.PP
 
98
You must have
 
99
INSERT
 
100
privilege on a table in order to insert into it\&. If
 
101
ON CONFLICT DO UPDATE
 
102
is present,
 
103
UPDATE
 
104
privilege on the table is also required\&.
 
105
.PP
 
106
If a column list is specified, you only need
 
107
INSERT
 
108
privilege on the listed columns\&. Similarly, when
 
109
ON CONFLICT DO UPDATE
 
110
is specified, you only need
 
111
UPDATE
 
112
privilege on the column(s) that are listed to be updated\&. However,
 
113
ON CONFLICT DO UPDATE
 
114
also requires
 
115
SELECT
 
116
privilege on any column whose values are read in the
 
117
ON CONFLICT DO UPDATE
 
118
expressions or
 
119
\fIcondition\fR\&.
 
120
.PP
 
121
Use of the
 
122
RETURNING
 
123
clause requires
 
124
SELECT
 
125
privilege on all columns mentioned in
 
126
RETURNING\&. If you use the
 
127
\fIquery\fR
 
128
clause to insert rows from a query, you of course need to have
 
129
SELECT
 
130
privilege on any table or column used in the query\&.
 
131
.SH "PARAMETERS"
 
132
.SS "Inserting"
 
133
.PP
 
134
This section covers parameters that may be used when only inserting new rows\&. Parameters
 
135
\fIexclusively\fR
 
136
used with the
 
137
ON CONFLICT
 
138
clause are described separately\&.
 
139
.PP
 
140
\fIwith_query\fR
 
141
.RS 4
 
142
The
 
143
WITH
 
144
clause allows you to specify one or more subqueries that can be referenced by name in the
 
145
\fBINSERT\fR
 
146
query\&. See
 
147
Section\ \&7.8
 
148
and
 
149
\fBSELECT\fR(7)
 
150
for details\&.
 
151
.sp
 
152
It is possible for the
 
153
\fIquery\fR
 
154
(\fBSELECT\fR
 
155
statement) to also contain a
 
156
WITH
 
157
clause\&. In such a case both sets of
 
158
\fIwith_query\fR
 
159
can be referenced within the
 
160
\fIquery\fR, but the second one takes precedence since it is more closely nested\&.
 
161
.RE
 
162
.PP
 
163
\fItable_name\fR
 
164
.RS 4
 
165
The name (optionally schema\-qualified) of an existing table\&.
 
166
.RE
 
167
.PP
 
168
\fIalias\fR
 
169
.RS 4
 
170
A substitute name for
 
171
\fItable_name\fR\&. When an alias is provided, it completely hides the actual name of the table\&. This is particularly useful when
 
172
ON CONFLICT DO UPDATE
 
173
targets a table named
 
174
\fIexcluded\fR, since that will otherwise be taken as the name of the special table representing rows proposed for insertion\&.
 
175
.RE
 
176
.PP
 
177
\fIcolumn_name\fR
 
178
.RS 4
 
179
The name of a column in the table named by
 
180
\fItable_name\fR\&. The column name can be qualified with a subfield name or array subscript, if needed\&. (Inserting into only some fields of a composite column leaves the other fields null\&.) When referencing a column with
 
181
ON CONFLICT DO UPDATE, do not include the table\*(Aqs name in the specification of a target column\&. For example,
 
182
INSERT INTO table_name \&.\&.\&. ON CONFLICT DO UPDATE SET table_name\&.col = 1
 
183
is invalid (this follows the general behavior for
 
184
\fBUPDATE\fR)\&.
 
185
.RE
 
186
.PP
 
187
OVERRIDING SYSTEM VALUE
 
188
.RS 4
 
189
Without this clause, it is an error to specify an explicit value (other than
 
190
DEFAULT) for an identity column defined as
 
191
GENERATED ALWAYS\&. This clause overrides that restriction\&.
 
192
.RE
 
193
.PP
 
194
OVERRIDING USER VALUE
 
195
.RS 4
 
196
If this clause is specified, then any values supplied for identity columns defined as
 
197
GENERATED BY DEFAULT
 
198
are ignored and the default sequence\-generated values are applied\&.
 
199
.sp
 
200
This clause is useful for example when copying values between tables\&. Writing
 
201
INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM tbl1
 
202
will copy from
 
203
tbl1
 
204
all columns that are not identity columns in
 
205
tbl2
 
206
while values for the identity columns in
 
207
tbl2
 
208
will be generated by the sequences associated with
 
209
tbl2\&.
 
210
.RE
 
211
.PP
 
212
DEFAULT VALUES
 
213
.RS 4
 
214
All columns will be filled with their default values\&. (An
 
215
OVERRIDING
 
216
clause is not permitted in this form\&.)
 
217
.RE
 
218
.PP
 
219
\fIexpression\fR
 
220
.RS 4
 
221
An expression or value to assign to the corresponding column\&.
 
222
.RE
 
223
.PP
 
224
DEFAULT
 
225
.RS 4
 
226
The corresponding column will be filled with its default value\&.
 
227
.RE
 
228
.PP
 
229
\fIquery\fR
 
230
.RS 4
 
231
A query (\fBSELECT\fR
 
232
statement) that supplies the rows to be inserted\&. Refer to the
 
233
\fBSELECT\fR(7)
 
234
statement for a description of the syntax\&.
 
235
.RE
 
236
.PP
 
237
\fIoutput_expression\fR
 
238
.RS 4
 
239
An expression to be computed and returned by the
 
240
\fBINSERT\fR
 
241
command after each row is inserted or updated\&. The expression can use any column names of the table named by
 
242
\fItable_name\fR\&. Write
 
243
*
 
244
to return all columns of the inserted or updated row(s)\&.
 
245
.RE
 
246
.PP
 
247
\fIoutput_name\fR
 
248
.RS 4
 
249
A name to use for a returned column\&.
 
250
.RE
 
251
.SS "ON CONFLICT Clause"
 
252
.PP
 
253
The optional
 
254
ON CONFLICT
 
255
clause specifies an alternative action to raising a unique violation or exclusion constraint violation error\&. For each individual row proposed for insertion, either the insertion proceeds, or, if an
 
256
\fIarbiter\fR
 
257
constraint or index specified by
 
258
\fIconflict_target\fR
 
259
is violated, the alternative
 
260
\fIconflict_action\fR
 
261
is taken\&.
 
262
ON CONFLICT DO NOTHING
 
263
simply avoids inserting a row as its alternative action\&.
 
264
ON CONFLICT DO UPDATE
 
265
updates the existing row that conflicts with the row proposed for insertion as its alternative action\&.
 
266
.PP
 
267
\fIconflict_target\fR
 
268
can perform
 
269
\fIunique index inference\fR\&. When performing inference, it consists of one or more
 
270
\fIindex_column_name\fR
 
271
columns and/or
 
272
\fIindex_expression\fR
 
273
expressions, and an optional
 
274
\fIindex_predicate\fR\&. All
 
275
\fItable_name\fR
 
276
unique indexes that, without regard to order, contain exactly the
 
277
\fIconflict_target\fR\-specified columns/expressions are inferred (chosen) as arbiter indexes\&. If an
 
278
\fIindex_predicate\fR
 
279
is specified, it must, as a further requirement for inference, satisfy arbiter indexes\&. Note that this means a non\-partial unique index (a unique index without a predicate) will be inferred (and thus used by
 
280
ON CONFLICT) if such an index satisfying every other criteria is available\&. If an attempt at inference is unsuccessful, an error is raised\&.
 
281
.PP
 
282
ON CONFLICT DO UPDATE
 
283
guarantees an atomic
 
284
\fBINSERT\fR
 
285
or
 
286
\fBUPDATE\fR
 
287
outcome; provided there is no independent error, one of those two outcomes is guaranteed, even under high concurrency\&. This is also known as
 
288
UPSERT
 
289
\(em
 
290
\(lqUPDATE or INSERT\(rq\&.
 
291
.PP
 
292
\fIconflict_target\fR
 
293
.RS 4
 
294
Specifies which conflicts
 
295
ON CONFLICT
 
296
takes the alternative action on by choosing
 
297
arbiter indexes\&. Either performs
 
298
\fIunique index inference\fR, or names a constraint explicitly\&. For
 
299
ON CONFLICT DO NOTHING, it is optional to specify a
 
300
\fIconflict_target\fR; when omitted, conflicts with all usable constraints (and unique indexes) are handled\&. For
 
301
ON CONFLICT DO UPDATE, a
 
302
\fIconflict_target\fR
 
303
\fImust\fR
 
304
be provided\&.
 
305
.RE
 
306
.PP
 
307
\fIconflict_action\fR
 
308
.RS 4
 
309
\fIconflict_action\fR
 
310
specifies an alternative
 
311
ON CONFLICT
 
312
action\&. It can be either
 
313
DO NOTHING, or a
 
314
DO UPDATE
 
315
clause specifying the exact details of the
 
316
UPDATE
 
317
action to be performed in case of a conflict\&. The
 
318
SET
 
319
and
 
320
WHERE
 
321
clauses in
 
322
ON CONFLICT DO UPDATE
 
323
have access to the existing row using the table\*(Aqs name (or an alias), and to rows proposed for insertion using the special
 
324
\fIexcluded\fR
 
325
table\&.
 
326
SELECT
 
327
privilege is required on any column in the target table where corresponding
 
328
\fIexcluded\fR
 
329
columns are read\&.
 
330
.sp
 
331
Note that the effects of all per\-row
 
332
BEFORE INSERT
 
333
triggers are reflected in
 
334
\fIexcluded\fR
 
335
values, since those effects may have contributed to the row being excluded from insertion\&.
 
336
.RE
 
337
.PP
 
338
\fIindex_column_name\fR
 
339
.RS 4
 
340
The name of a
 
341
\fItable_name\fR
 
342
column\&. Used to infer arbiter indexes\&. Follows
 
343
\fBCREATE INDEX\fR
 
344
format\&.
 
345
SELECT
 
346
privilege on
 
347
\fIindex_column_name\fR
 
348
is required\&.
 
349
.RE
 
350
.PP
 
351
\fIindex_expression\fR
 
352
.RS 4
 
353
Similar to
 
354
\fIindex_column_name\fR, but used to infer expressions on
 
355
\fItable_name\fR
 
356
columns appearing within index definitions (not simple columns)\&. Follows
 
357
\fBCREATE INDEX\fR
 
358
format\&.
 
359
SELECT
 
360
privilege on any column appearing within
 
361
\fIindex_expression\fR
 
362
is required\&.
 
363
.RE
 
364
.PP
 
365
\fIcollation\fR
 
366
.RS 4
 
367
When specified, mandates that corresponding
 
368
\fIindex_column_name\fR
 
369
or
 
370
\fIindex_expression\fR
 
371
use a particular collation in order to be matched during inference\&. Typically this is omitted, as collations usually do not affect whether or not a constraint violation occurs\&. Follows
 
372
\fBCREATE INDEX\fR
 
373
format\&.
 
374
.RE
 
375
.PP
 
376
\fIopclass\fR
 
377
.RS 4
 
378
When specified, mandates that corresponding
 
379
\fIindex_column_name\fR
 
380
or
 
381
\fIindex_expression\fR
 
382
use particular operator class in order to be matched during inference\&. Typically this is omitted, as the
 
383
\fIequality\fR
 
384
semantics are often equivalent across a type\*(Aqs operator classes anyway, or because it\*(Aqs sufficient to trust that the defined unique indexes have the pertinent definition of equality\&. Follows
 
385
\fBCREATE INDEX\fR
 
386
format\&.
 
387
.RE
 
388
.PP
 
389
\fIindex_predicate\fR
 
390
.RS 4
 
391
Used to allow inference of partial unique indexes\&. Any indexes that satisfy the predicate (which need not actually be partial indexes) can be inferred\&. Follows
 
392
\fBCREATE INDEX\fR
 
393
format\&.
 
394
SELECT
 
395
privilege on any column appearing within
 
396
\fIindex_predicate\fR
 
397
is required\&.
 
398
.RE
 
399
.PP
 
400
\fIconstraint_name\fR
 
401
.RS 4
 
402
Explicitly specifies an arbiter
 
403
\fIconstraint\fR
 
404
by name, rather than inferring a constraint or index\&.
 
405
.RE
 
406
.PP
 
407
\fIcondition\fR
 
408
.RS 4
 
409
An expression that returns a value of type
 
410
boolean\&. Only rows for which this expression returns
 
411
true
 
412
will be updated, although all rows will be locked when the
 
413
ON CONFLICT DO UPDATE
 
414
action is taken\&. Note that
 
415
\fIcondition\fR
 
416
is evaluated last, after a conflict has been identified as a candidate to update\&.
 
417
.RE
 
418
.PP
 
419
Note that exclusion constraints are not supported as arbiters with
 
420
ON CONFLICT DO UPDATE\&. In all cases, only
 
421
NOT DEFERRABLE
 
422
constraints and unique indexes are supported as arbiters\&.
 
423
.PP
 
424
\fBINSERT\fR
 
425
with an
 
426
ON CONFLICT DO UPDATE
 
427
clause is a
 
428
\(lqdeterministic\(rq
 
429
statement\&. This means that the command will not be allowed to affect any single existing row more than once; a cardinality violation error will be raised when this situation arises\&. Rows proposed for insertion should not duplicate each other in terms of attributes constrained by an arbiter index or constraint\&.
 
430
.PP
 
431
Note that it is currently not supported for the
 
432
ON CONFLICT DO UPDATE
 
433
clause of an
 
434
\fBINSERT\fR
 
435
applied to a partitioned table to update the partition key of a conflicting row such that it requires the row be moved to a new partition\&.
 
436
.if n \{\
 
437
.sp
 
438
.\}
 
439
.RS 4
 
440
.it 1 an-trap
 
441
.nr an-no-space-flag 1
 
442
.nr an-break-flag 1
 
443
.br
 
444
.ps +1
 
445
\fBTip\fR
 
446
.ps -1
 
447
.br
 
448
.PP
 
449
It is often preferable to use unique index inference rather than naming a constraint directly using
 
450
ON CONFLICT ON CONSTRAINT
 
451
\fI constraint_name\fR\&. Inference will continue to work correctly when the underlying index is replaced by another more or less equivalent index in an overlapping way, for example when using
 
452
CREATE UNIQUE INDEX \&.\&.\&. CONCURRENTLY
 
453
before dropping the index being replaced\&.
 
454
.sp .5v
 
455
.RE
 
456
.SH "OUTPUTS"
 
457
.PP
 
458
On successful completion, an
 
459
\fBINSERT\fR
 
460
command returns a command tag of the form
 
461
.sp
 
462
.if n \{\
 
463
.RS 4
 
464
.\}
 
465
.nf
 
466
INSERT \fIoid\fR \fIcount\fR
 
467
.fi
 
468
.if n \{\
 
469
.RE
 
470
.\}
 
471
.sp
 
472
The
 
473
\fIcount\fR
 
474
is the number of rows inserted or updated\&. If
 
475
\fIcount\fR
 
476
is exactly one, and the target table has OIDs, then
 
477
\fIoid\fR
 
478
is the
 
479
OID
 
480
assigned to the inserted row\&. The single row must have been inserted rather than updated\&. Otherwise
 
481
\fIoid\fR
 
482
is zero\&.
 
483
.PP
 
484
If the
 
485
\fBINSERT\fR
 
486
command contains a
 
487
RETURNING
 
488
clause, the result will be similar to that of a
 
489
\fBSELECT\fR
 
490
statement containing the columns and values defined in the
 
491
RETURNING
 
492
list, computed over the row(s) inserted or updated by the command\&.
 
493
.SH "NOTES"
 
494
.PP
 
495
If the specified table is a partitioned table, each row is routed to the appropriate partition and inserted into it\&. If the specified table is a partition, an error will occur if one of the input rows violates the partition constraint\&.
 
496
.SH "EXAMPLES"
 
497
.PP
 
498
Insert a single row into table
 
499
films:
 
500
.sp
 
501
.if n \{\
 
502
.RS 4
 
503
.\}
 
504
.nf
 
505
INSERT INTO films VALUES
 
506
    (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, \*(Aq1971\-07\-13\*(Aq, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq);
 
507
.fi
 
508
.if n \{\
 
509
.RE
 
510
.\}
 
511
.PP
 
512
In this example, the
 
513
len
 
514
column is omitted and therefore it will have the default value:
 
515
.sp
 
516
.if n \{\
 
517
.RS 4
 
518
.\}
 
519
.nf
 
520
INSERT INTO films (code, title, did, date_prod, kind)
 
521
    VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, \*(Aq1961\-06\-16\*(Aq, \*(AqDrama\*(Aq);
 
522
.fi
 
523
.if n \{\
 
524
.RE
 
525
.\}
 
526
.PP
 
527
This example uses the
 
528
DEFAULT
 
529
clause for the date columns rather than specifying a value:
 
530
.sp
 
531
.if n \{\
 
532
.RS 4
 
533
.\}
 
534
.nf
 
535
INSERT INTO films VALUES
 
536
    (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, DEFAULT, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq);
 
537
INSERT INTO films (code, title, did, date_prod, kind)
 
538
    VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, DEFAULT, \*(AqDrama\*(Aq);
 
539
.fi
 
540
.if n \{\
 
541
.RE
 
542
.\}
 
543
.PP
 
544
To insert a row consisting entirely of default values:
 
545
.sp
 
546
.if n \{\
 
547
.RS 4
 
548
.\}
 
549
.nf
 
550
INSERT INTO films DEFAULT VALUES;
 
551
.fi
 
552
.if n \{\
 
553
.RE
 
554
.\}
 
555
.PP
 
556
To insert multiple rows using the multirow
 
557
\fBVALUES\fR
 
558
syntax:
 
559
.sp
 
560
.if n \{\
 
561
.RS 4
 
562
.\}
 
563
.nf
 
564
INSERT INTO films (code, title, did, date_prod, kind) VALUES
 
565
    (\*(AqB6717\*(Aq, \*(AqTampopo\*(Aq, 110, \*(Aq1985\-02\-10\*(Aq, \*(AqComedy\*(Aq),
 
566
    (\*(AqHG120\*(Aq, \*(AqThe Dinner Game\*(Aq, 140, DEFAULT, \*(AqComedy\*(Aq);
 
567
.fi
 
568
.if n \{\
 
569
.RE
 
570
.\}
 
571
.PP
 
572
This example inserts some rows into table
 
573
films
 
574
from a table
 
575
tmp_films
 
576
with the same column layout as
 
577
films:
 
578
.sp
 
579
.if n \{\
 
580
.RS 4
 
581
.\}
 
582
.nf
 
583
INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < \*(Aq2004\-05\-07\*(Aq;
 
584
.fi
 
585
.if n \{\
 
586
.RE
 
587
.\}
 
588
.PP
 
589
This example inserts into array columns:
 
590
.sp
 
591
.if n \{\
 
592
.RS 4
 
593
.\}
 
594
.nf
 
595
\-\- Create an empty 3x3 gameboard for noughts\-and\-crosses
 
596
INSERT INTO tictactoe (game, board[1:3][1:3])
 
597
    VALUES (1, \*(Aq{{" "," "," "},{" "," "," "},{" "," "," "}}\*(Aq);
 
598
\-\- The subscripts in the above example aren\*(Aqt really needed
 
599
INSERT INTO tictactoe (game, board)
 
600
    VALUES (2, \*(Aq{{X," "," "},{" ",O," "},{" ",X," "}}\*(Aq);
 
601
.fi
 
602
.if n \{\
 
603
.RE
 
604
.\}
 
605
.PP
 
606
Insert a single row into table
 
607
distributors, returning the sequence number generated by the
 
608
DEFAULT
 
609
clause:
 
610
.sp
 
611
.if n \{\
 
612
.RS 4
 
613
.\}
 
614
.nf
 
615
INSERT INTO distributors (did, dname) VALUES (DEFAULT, \*(AqXYZ Widgets\*(Aq)
 
616
   RETURNING did;
 
617
.fi
 
618
.if n \{\
 
619
.RE
 
620
.\}
 
621
.PP
 
622
Increment the sales count of the salesperson who manages the account for Acme Corporation, and record the whole updated row along with current time in a log table:
 
623
.sp
 
624
.if n \{\
 
625
.RS 4
 
626
.\}
 
627
.nf
 
628
WITH upd AS (
 
629
  UPDATE employees SET sales_count = sales_count + 1 WHERE id =
 
630
    (SELECT sales_person FROM accounts WHERE name = \*(AqAcme Corporation\*(Aq)
 
631
    RETURNING *
 
632
)
 
633
INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
 
634
.fi
 
635
.if n \{\
 
636
.RE
 
637
.\}
 
638
.PP
 
639
Insert or update new distributors as appropriate\&. Assumes a unique index has been defined that constrains values appearing in the
 
640
did
 
641
column\&. Note that the special
 
642
\fIexcluded\fR
 
643
table is used to reference values originally proposed for insertion:
 
644
.sp
 
645
.if n \{\
 
646
.RS 4
 
647
.\}
 
648
.nf
 
649
INSERT INTO distributors (did, dname)
 
650
    VALUES (5, \*(AqGizmo Transglobal\*(Aq), (6, \*(AqAssociated Computing, Inc\*(Aq)
 
651
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED\&.dname;
 
652
.fi
 
653
.if n \{\
 
654
.RE
 
655
.\}
 
656
.PP
 
657
Insert a distributor, or do nothing for rows proposed for insertion when an existing, excluded row (a row with a matching constrained column or columns after before row insert triggers fire) exists\&. Example assumes a unique index has been defined that constrains values appearing in the
 
658
did
 
659
column:
 
660
.sp
 
661
.if n \{\
 
662
.RS 4
 
663
.\}
 
664
.nf
 
665
INSERT INTO distributors (did, dname) VALUES (7, \*(AqRedline GmbH\*(Aq)
 
666
    ON CONFLICT (did) DO NOTHING;
 
667
.fi
 
668
.if n \{\
 
669
.RE
 
670
.\}
 
671
.PP
 
672
Insert or update new distributors as appropriate\&. Example assumes a unique index has been defined that constrains values appearing in the
 
673
did
 
674
column\&.
 
675
WHERE
 
676
clause is used to limit the rows actually updated (any existing row not updated will still be locked, though):
 
677
.sp
 
678
.if n \{\
 
679
.RS 4
 
680
.\}
 
681
.nf
 
682
\-\- Don\*(Aqt update existing distributors based in a certain ZIP code
 
683
INSERT INTO distributors AS d (did, dname) VALUES (8, \*(AqAnvil Distribution\*(Aq)
 
684
    ON CONFLICT (did) DO UPDATE
 
685
    SET dname = EXCLUDED\&.dname || \*(Aq (formerly \*(Aq || d\&.dname || \*(Aq)\*(Aq
 
686
    WHERE d\&.zipcode <> \*(Aq21201\*(Aq;
 
687
 
 
688
\-\- Name a constraint directly in the statement (uses associated
 
689
\-\- index to arbitrate taking the DO NOTHING action)
 
690
INSERT INTO distributors (did, dname) VALUES (9, \*(AqAntwerp Design\*(Aq)
 
691
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;
 
692
.fi
 
693
.if n \{\
 
694
.RE
 
695
.\}
 
696
.PP
 
697
Insert new distributor if possible; otherwise
 
698
DO NOTHING\&. Example assumes a unique index has been defined that constrains values appearing in the
 
699
did
 
700
column on a subset of rows where the
 
701
is_active
 
702
Boolean column evaluates to
 
703
true:
 
704
.sp
 
705
.if n \{\
 
706
.RS 4
 
707
.\}
 
708
.nf
 
709
\-\- This statement could infer a partial unique index on "did"
 
710
\-\- with a predicate of "WHERE is_active", but it could also
 
711
\-\- just use a regular unique constraint on "did"
 
712
INSERT INTO distributors (did, dname) VALUES (10, \*(AqConrad International\*(Aq)
 
713
    ON CONFLICT (did) WHERE is_active DO NOTHING;
 
714
.fi
 
715
.if n \{\
 
716
.RE
 
717
.\}
 
718
.SH "COMPATIBILITY"
 
719
.PP
 
720
\fBINSERT\fR
 
721
conforms to the SQL standard, except that the
 
722
RETURNING
 
723
clause is a
 
724
PostgreSQL
 
725
extension, as is the ability to use
 
726
WITH
 
727
with
 
728
\fBINSERT\fR, and the ability to specify an alternative action with
 
729
ON CONFLICT\&. Also, the case in which a column name list is omitted, but not all the columns are filled from the
 
730
VALUES
 
731
clause or
 
732
\fIquery\fR, is disallowed by the standard\&.
 
733
.PP
 
734
The SQL standard specifies that
 
735
OVERRIDING SYSTEM VALUE
 
736
can only be specified if an identity column that is generated always exists\&. PostgreSQL allows the clause in any case and ignores it if it is not applicable\&.
 
737
.PP
 
738
Possible limitations of the
 
739
\fIquery\fR
 
740
clause are documented under
 
741
\fBSELECT\fR(7)\&.