From d4c573d8e81ed28ee335e9cb2115098b99d38e71 Mon Sep 17 00:00:00 2001
From: Dean Rasheed <dean.a.rasheed@gmail.com>
Date: Wed, 13 Mar 2024 13:15:07 +0000
Subject: [PATCH] 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
---
doc/src/sgml/ref/merge.sgml | 36 ++++++++++++++++++++++++++++--------
1 file changed, 28 insertions(+), 8 deletions(-)
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index 8e1b7c7fe55..815b9989ae9 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -44,7 +44,9 @@ INSERT [( <replaceable class="parameter">column_name</replaceable> [, ...] )]
<phrase>and <replaceable class="parameter">merge_update</replaceable> is:</phrase>
UPDATE SET { <replaceable class="parameter">column_name</replaceable> = { <replaceable class="parameter">expression</replaceable> | DEFAULT } |
- ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
+ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = [ ROW ] ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) |
+ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( <replaceable class="parameter">sub-SELECT</replaceable> )
+ } [, ...]
<phrase>and <replaceable class="parameter">merge_delete</replaceable> is:</phrase>
@@ -128,6 +130,19 @@ DELETE
<title>Parameters</title>
<variablelist>
+ <varlistentry>
+ <term><replaceable class="parameter">with_query</replaceable></term>
+ <listitem>
+ <para>
+ The <literal>WITH</literal> clause allows you to specify one or more
+ subqueries that can be referenced by name in the <command>MERGE</command>
+ query. See <xref linkend="queries-with"/> and <xref linkend="sql-select"/>
+ for details. Note that <literal>WITH RECURSIVE</literal> is not supported
+ by <command>MERGE</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><replaceable class="parameter">target_table_name</replaceable></term>
<listitem>
@@ -383,9 +398,10 @@ DELETE
An expression to assign to the column. If used in a
<literal>WHEN MATCHED</literal> clause, the expression can use values
from the original row in the target table, and values from the
- <literal>data_source</literal> row.
+ <replaceable class="parameter">data_source</replaceable> row.
If used in a <literal>WHEN NOT MATCHED</literal> clause, the
- expression can use values from the <literal>data_source</literal>.
+ expression can use values from the
+ <replaceable class="parameter">data_source</replaceable> row.
</para>
</listitem>
</varlistentry>
@@ -401,13 +417,17 @@ DELETE
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">with_query</replaceable></term>
+ <term><replaceable class="parameter">sub-SELECT</replaceable></term>
<listitem>
<para>
- The <literal>WITH</literal> clause allows you to specify one or more
- subqueries that can be referenced by name in the <command>MERGE</command>
- query. See <xref linkend="queries-with"/> and <xref linkend="sql-select"/>
- for details.
+ A <literal>SELECT</literal> sub-query that produces as many output columns
+ as are listed in the parenthesized column list preceding it. The
+ sub-query must yield no more than one row when executed. If it
+ yields one row, its column values are assigned to the target columns;
+ if it yields no rows, NULL values are assigned to the target columns.
+ The sub-query can refer to values from the original row in the target table,
+ and values from the <replaceable class="parameter">data_source</replaceable>
+ row.
</para>
</listitem>
</varlistentry>