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

diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index 8e1b7c7fe5556c1f24da82355b160e6bd75cfdeb..815b9989ae96134dc1dcdda38b16d5694895b5ca 100644 (file)
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -44,7 +44,9 @@ INSERT [( column_name [, ...] )]
 and merge_update is:
 
 UPDATE SET { column_name = { expression | DEFAULT } |
-             ( column_name [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...]
+             ( column_name [, ...] ) = [ ROW ] ( { expression | DEFAULT } [, ...] ) |
+             ( column_name [, ...] ) = ( sub-SELECT )
+           } [, ...]
 
 and merge_delete is:
 
@@ -128,6 +130,19 @@ DELETE
   Parameters
 
   
+   
+    with_query
+    
+     
+      The WITH clause allows you to specify one or more
+      subqueries that can be referenced by name in the MERGE
+      query. See  and 
+      for details.  Note that WITH RECURSIVE is not supported
+      by MERGE.
+     
+    
+   
+
    
     target_table_name
     
@@ -383,9 +398,10 @@ DELETE
       An expression to assign to the column.  If used in a
       WHEN MATCHED clause, the expression can use values
       from the original row in the target table, and values from the
-      <literal>data_source> row.
+      <replaceable class="parameter">data_source> row.
       If used in a WHEN NOT MATCHED clause, the
-      expression can use values from the data_source.
+      expression can use values from the
+      data_source row.
      
     
    
@@ -401,13 +417,17 @@ DELETE
    
 
    
-    with_query
+    sub-SELECT
     
      
-      The WITH clause allows you to specify one or more
-      subqueries that can be referenced by name in the MERGE
-      query. See  and 
-      for details.
+      A SELECT 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 data_source
+      row.