@@ -34,7 +34,8 @@ USING <replaceable class="parameter">data_source</replaceable> ON <replaceable c
34
34
<phrase>and <replaceable class="parameter">when_clause</replaceable> is:</phrase>
35
35
36
36
{ WHEN MATCHED [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
37
- WHEN NOT MATCHED [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_insert</replaceable> | DO NOTHING } }
37
+ WHEN NOT MATCHED BY SOURCE [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
38
+ WHEN NOT MATCHED [ BY TARGET ] [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_insert</replaceable> | DO NOTHING } }
38
39
39
40
<phrase>and <replaceable class="parameter">merge_insert</replaceable> is:</phrase>
40
41
73
74
from <replaceable class="parameter">data_source</replaceable> to
74
75
the target table
75
76
producing zero or more candidate change rows. For each candidate change
76
- row, the status of <literal>MATCHED</literal> or <literal>NOT MATCHED</literal>
77
+ row, the status of <literal>MATCHED</literal>,
78
+ <literal>NOT MATCHED BY SOURCE</literal>,
79
+ or <literal>NOT MATCHED [BY TARGET]</literal>
77
80
is set just once, after which <literal>WHEN</literal> clauses are evaluated
78
81
in the order specified. For each candidate change row, the first clause to
79
82
evaluate as true is executed. No more than one <literal>WHEN</literal>
@@ -257,6 +260,16 @@ DELETE
257
260
only reference the target table's
258
261
columns can affect which action is taken, often in surprising ways.
259
262
</para>
263
+ <para>
264
+ If both <literal>WHEN NOT MATCHED BY SOURCE</literal> and
265
+ <literal>WHEN NOT MATCHED [BY TARGET]</literal> clauses are specified,
266
+ the <command>MERGE</command> command will perform a <literal>FULL</literal>
267
+ join between <replaceable class="parameter">data_source</replaceable>
268
+ and the target table. For this to work, at least one
269
+ <replaceable class="parameter">join_condition</replaceable> subexpression
270
+ must use an operator that can support a hash join, or all of the
271
+ subexpressions must use operators that can support a merge join.
272
+ </para>
260
273
</warning>
261
274
</listitem>
262
275
</varlistentry>
@@ -267,19 +280,41 @@ DELETE
267
280
<para>
268
281
At least one <literal>WHEN</literal> clause is required.
269
282
</para>
283
+ <para>
284
+ The <literal>WHEN</literal> clause may specify <literal>WHEN MATCHED</literal>,
285
+ <literal>WHEN NOT MATCHED BY SOURCE</literal>, or
286
+ <literal>WHEN NOT MATCHED [BY TARGET]</literal>.
287
+ Note that the <acronym>SQL</acronym> standard only defines
288
+ <literal>WHEN MATCHED</literal> and <literal>WHEN NOT MATCHED</literal>
289
+ (which is defined to mean no matching target row).
290
+ <literal>WHEN NOT MATCHED BY SOURCE</literal> is an extension to the
291
+ <acronym>SQL</acronym> standard, as is the option to append
292
+ <literal>BY TARGET</literal> to <literal>WHEN NOT MATCHED</literal>, to
293
+ make its meaning more explicit.
294
+ </para>
270
295
<para>
271
296
If the <literal>WHEN</literal> clause specifies <literal>WHEN MATCHED</literal>
272
297
and the candidate change row matches a row in the
273
- target table,
274
- the <literal>WHEN</literal> clause is executed if the
298
+ <replaceable class="parameter">data_source</replaceable> to a row in the
299
+ target table, the <literal>WHEN</literal> clause is executed if the
300
+ <replaceable class="parameter">condition</replaceable> is
301
+ absent or it evaluates to <literal>true</literal>.
302
+ </para>
303
+ <para>
304
+ If the <literal>WHEN</literal> clause specifies
305
+ <literal>WHEN NOT MATCHED BY SOURCE</literal> and the candidate change
306
+ row represents a row in the target table that does not match a row in the
307
+ <replaceable class="parameter">data_source</replaceable>, the
308
+ <literal>WHEN</literal> clause is executed if the
275
309
<replaceable class="parameter">condition</replaceable> is
276
310
absent or it evaluates to <literal>true</literal>.
277
311
</para>
278
312
<para>
279
- Conversely, if the <literal>WHEN</literal> clause specifies
280
- <literal>WHEN NOT MATCHED</literal>
281
- and the candidate change row does not match a row in the
282
- target table,
313
+ If the <literal>WHEN</literal> clause specifies
314
+ <literal>WHEN NOT MATCHED [BY TARGET]</literal> and the candidate change
315
+ row represents a row in the
316
+ <replaceable class="parameter">data_source</replaceable> that does not
317
+ match a row in the target table,
283
318
the <literal>WHEN</literal> clause is executed if the
284
319
<replaceable class="parameter">condition</replaceable> is
285
320
absent or it evaluates to <literal>true</literal>.
@@ -299,7 +334,10 @@ DELETE
299
334
<para>
300
335
A condition on a <literal>WHEN MATCHED</literal> clause can refer to columns
301
336
in both the source and the target relations. A condition on a
302
- <literal>WHEN NOT MATCHED</literal> clause can only refer to columns from
337
+ <literal>WHEN NOT MATCHED BY SOURCE</literal> clause can only refer to
338
+ columns from the target relation, since by definition there is no matching
339
+ source row. A condition on a <literal>WHEN NOT MATCHED [BY TARGET]</literal>
340
+ clause can only refer to columns from
303
341
the source relation, since by definition there is no matching target row.
304
342
Only the system attributes from the target table are accessible.
305
343
</para>
@@ -423,8 +461,10 @@ DELETE
423
461
<literal>WHEN MATCHED</literal> clause, the expression can use values
424
462
from the original row in the target table, and values from the
425
463
<replaceable class="parameter">data_source</replaceable> row.
426
- If used in a <literal>WHEN NOT MATCHED</literal> clause, the
427
- expression can use values from the
464
+ If used in a <literal>WHEN NOT MATCHED BY SOURCE</literal> clause, the
465
+ expression can only use values from the original row in the target table.
466
+ If used in a <literal>WHEN NOT MATCHED [BY TARGET]</literal> clause, the
467
+ expression can only use values from the
428
468
<replaceable class="parameter">data_source</replaceable> row.
429
469
</para>
430
470
</listitem>
@@ -449,9 +489,12 @@ DELETE
449
489
sub-query must yield no more than one row when executed. If it
450
490
yields one row, its column values are assigned to the target columns;
451
491
if it yields no rows, NULL values are assigned to the target columns.
452
- The sub-query can refer to values from the original row in the target table,
453
- and values from the <replaceable class="parameter">data_source</replaceable>
454
- row.
492
+ If used in a <literal>WHEN MATCHED</literal> clause, the sub-query can
493
+ refer to values from the original row in the target table, and values
494
+ from the <replaceable class="parameter">data_source</replaceable> row.
495
+ If used in a <literal>WHEN NOT MATCHED BY SOURCE</literal> clause, the
496
+ sub-query can only refer to values from the original row in the target
497
+ table.
455
498
</para>
456
499
</listitem>
457
500
</varlistentry>
@@ -535,8 +578,9 @@ MERGE <replaceable class="parameter">total_count</replaceable>
535
578
<orderedlist>
536
579
<listitem>
537
580
<para>
538
- Evaluate whether each row is <literal>MATCHED</literal> or
539
- <literal>NOT MATCHED</literal>.
581
+ Evaluate whether each row is <literal>MATCHED</literal>,
582
+ <literal>NOT MATCHED BY SOURCE</literal>, or
583
+ <literal>NOT MATCHED [BY TARGET]</literal>.
540
584
</para>
541
585
</listitem>
542
586
<listitem>
@@ -615,7 +659,8 @@ MERGE <replaceable class="parameter">total_count</replaceable>
615
659
<para>
616
660
If a <literal>WHEN</literal> clause omits an <literal>AND</literal>
617
661
sub-clause, it becomes the final reachable clause of that
618
- kind (<literal>MATCHED</literal> or <literal>NOT MATCHED</literal>).
662
+ kind (<literal>MATCHED</literal>, <literal>NOT MATCHED BY SOURCE</literal>,
663
+ or <literal>NOT MATCHED [BY TARGET]</literal>).
619
664
If a later <literal>WHEN</literal> clause of that kind
620
665
is specified it would be provably unreachable and an error is raised.
621
666
If no final reachable clause is specified of either kind, it is
@@ -701,6 +746,23 @@ RETURNING merge_action(), w.*;
701
746
temporary table recently loaded into the database.
702
747
</para>
703
748
749
+ <para>
750
+ Update <literal>wines</literal> based on a replacement wine list, inserting
751
+ rows for any new stock, updating modified stock entries, and deleting any
752
+ wines not present in the new list.
753
+ <programlisting>
754
+ MERGE INTO wines w
755
+ USING new_wine_list s
756
+ ON s.winename = w.winename
757
+ WHEN NOT MATCHED BY TARGET THEN
758
+ INSERT VALUES(s.winename, s.stock)
759
+ WHEN MATCHED AND w.stock != s.stock THEN
760
+ UPDATE SET stock = s.stock
761
+ WHEN NOT MATCHED BY SOURCE THEN
762
+ DELETE;
763
+ </programlisting>
764
+ </para>
765
+
704
766
</refsect1>
705
767
706
768
<refsect1>
@@ -709,7 +771,9 @@ RETURNING merge_action(), w.*;
709
771
This command conforms to the <acronym>SQL</acronym> standard.
710
772
</para>
711
773
<para>
712
- The <literal>WITH</literal> clause, <literal>DO NOTHING</literal> action,
774
+ The <literal>WITH</literal> clause, <literal>BY SOURCE</literal> and
775
+ <literal>BY TARGET</literal> qualifiers to
776
+ <literal>WHEN NOT MATCHED</literal>, <literal>DO NOTHING</literal> action,
713
777
and <literal>RETURNING</literal> clause are extensions to the
714
778
<acronym>SQL</acronym> standard.
715
779
</para>
0 commit comments