From 97d4262683acb586778af2b2a3721fa7cdc402f1 Mon Sep 17 00:00:00 2001 From: Dean Rasheed Date: Wed, 13 Mar 2024 13:16:24 +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 7a8ac40259..e745fbd586 100644 --- 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 @@ -393,9 +408,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 - data_source row. + 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. @@ -411,13 +427,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.