Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 97d4262

Browse files
committed
doc: Improve a couple of places in the MERGE docs.
In the synopsis, make the syntax for merge_update consistent with the syntax for a plain UPDATE command. It was missing the optional "ROW" keyword that can be used in a multi-column assignment, and the option to assign from a multi-column subquery, both of which have been supported by MERGE since it was introduced. In the parameters section for the with_query parameter, mention that WITH RECURSIVE isn't supported, since this is different from plain INSERT, UPDATE, and DELETE commands. While at it, move that entry to the top of the list, for consistency with the other pages. Back-patch to v15, where MERGE was introduced. Discussion: https://postgr.es/m/CAEZATCWoQyWkMFfu7JXXQr8dA6%3DgxjhYzgpuBP2oz0QoJTxGWw%40mail.gmail.com
1 parent a3da95d commit 97d4262

File tree

1 file changed

+28
-8
lines changed

1 file changed

+28
-8
lines changed

doc/src/sgml/ref/merge.sgml

+28-8
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,9 @@ INSERT [( <replaceable class="parameter">column_name</replaceable> [, ...] )]
4444
<phrase>and <replaceable class="parameter">merge_update</replaceable> is:</phrase>
4545

4646
UPDATE SET { <replaceable class="parameter">column_name</replaceable> = { <replaceable class="parameter">expression</replaceable> | DEFAULT } |
47-
( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
47+
( <replaceable class="parameter">column_name</replaceable> [, ...] ) = [ ROW ] ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) |
48+
( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( <replaceable class="parameter">sub-SELECT</replaceable> )
49+
} [, ...]
4850

4951
<phrase>and <replaceable class="parameter">merge_delete</replaceable> is:</phrase>
5052

@@ -128,6 +130,19 @@ DELETE
128130
<title>Parameters</title>
129131

130132
<variablelist>
133+
<varlistentry>
134+
<term><replaceable class="parameter">with_query</replaceable></term>
135+
<listitem>
136+
<para>
137+
The <literal>WITH</literal> clause allows you to specify one or more
138+
subqueries that can be referenced by name in the <command>MERGE</command>
139+
query. See <xref linkend="queries-with"/> and <xref linkend="sql-select"/>
140+
for details. Note that <literal>WITH RECURSIVE</literal> is not supported
141+
by <command>MERGE</command>.
142+
</para>
143+
</listitem>
144+
</varlistentry>
145+
131146
<varlistentry>
132147
<term><replaceable class="parameter">target_table_name</replaceable></term>
133148
<listitem>
@@ -393,9 +408,10 @@ DELETE
393408
An expression to assign to the column. If used in a
394409
<literal>WHEN MATCHED</literal> clause, the expression can use values
395410
from the original row in the target table, and values from the
396-
<replaceable>data_source</replaceable> row.
411+
<replaceable class="parameter">data_source</replaceable> row.
397412
If used in a <literal>WHEN NOT MATCHED</literal> clause, the
398-
expression can use values from the <replaceable>data_source</replaceable>.
413+
expression can use values from the
414+
<replaceable class="parameter">data_source</replaceable> row.
399415
</para>
400416
</listitem>
401417
</varlistentry>
@@ -411,13 +427,17 @@ DELETE
411427
</varlistentry>
412428

413429
<varlistentry>
414-
<term><replaceable class="parameter">with_query</replaceable></term>
430+
<term><replaceable class="parameter">sub-SELECT</replaceable></term>
415431
<listitem>
416432
<para>
417-
The <literal>WITH</literal> clause allows you to specify one or more
418-
subqueries that can be referenced by name in the <command>MERGE</command>
419-
query. See <xref linkend="queries-with"/> and <xref linkend="sql-select"/>
420-
for details.
433+
A <literal>SELECT</literal> sub-query that produces as many output columns
434+
as are listed in the parenthesized column list preceding it. The
435+
sub-query must yield no more than one row when executed. If it
436+
yields one row, its column values are assigned to the target columns;
437+
if it yields no rows, NULL values are assigned to the target columns.
438+
The sub-query can refer to values from the original row in the target table,
439+
and values from the <replaceable class="parameter">data_source</replaceable>
440+
row.
421441
</para>
422442
</listitem>
423443
</varlistentry>

0 commit comments

Comments
 (0)