Add SQL Support for MERGE INTO In Presto #20578 (documentation)

Added MERGE INTO statement documentation.

Author: acarpente-denodo

presto-docs/src/main/sphinx/connector/iceberg.rst

@@ -1277,6 +1277,8 @@ SQL Operation                  Presto Java   Presto C++   Comments
 ``DESCRIBE``                   Yes           Yes
 
 ``UPDATE``                     Yes           No
+
+``MERGE``                      Yes           No
 ============================== ============= ============ ============================================================================
 
 The Iceberg connector supports querying and manipulating Iceberg tables and schemas
@@ -1727,11 +1729,11 @@ For example, ``DESCRIBE`` from the partitioned Iceberg table ``customer``:
      comment   | varchar |       |
      (3 rows)
 
-UPDATE
-^^^^^^
+UPDATE and MERGE
+^^^^^^^^^^^^^^^^
 
-The Iceberg connector supports :doc:`../sql/update` operations on Iceberg
-tables. Only some tables support updates. These tables must be at minimum format
+The Iceberg connector supports :doc:`../sql/update` and :doc:`../sql/merge` operations on Iceberg
+tables. Only some tables support them. These tables must be at minimum format
 version 2, and the ``write.update.mode`` must be set to `merge-on-read`.
 
 .. code-block:: sql
@@ -1751,6 +1753,16 @@ updates.
 
     Query 20250204_010445_00022_ymwi5 failed: Iceberg table updates require at least format version 2 and update mode must be merge-on-read
 
+Iceberg tables do not support running multiple ``MERGE`` statements on the same table in parallel. If two or more ``MERGE`` operations are executed concurrently on the same Iceberg table:
+
+* The first operation to complete will succeed.
+* Subsequent operations will fail due to conflicting writes and will return the following error:
+
+.. code-block:: text
+
+    Failed to commit Iceberg update to table: <table name>
+    Found conflicting files that can contain records matching true
+
 Schema Evolution
 ----------------
 

presto-docs/src/main/sphinx/sql.rst

@@ -38,6 +38,7 @@ This chapter describes the SQL syntax used in Presto.
     sql/grant
     sql/grant-roles
     sql/insert
+    sql/merge
     sql/prepare
     sql/refresh-materialized-view
     sql/reset-session

presto-docs/src/main/sphinx/sql/merge.rst

@@ -0,0 +1,71 @@
+=====
+MERGE
+=====
+
+Synopsis
+--------
+
+.. code-block:: text
+
+    MERGE INTO target_table [ [ AS ]  target_alias ]
+    USING { source_table | query } [ [ AS ] source_alias ]
+    ON search_condition
+    WHEN MATCHED THEN
+        UPDATE SET ( column = expression [, ...] )
+    WHEN NOT MATCHED THEN
+        INSERT [ column_list ]
+        VALUES (expression, ...)
+
+Description
+-----------
+
+The ``MERGE`` statement inserts or updates rows in a ``target_table`` based on the contents of the ``source_table``.
+The ``search_condition`` defines a relation between the source and target tables.
+When the condition is met, the target row is updated. When the condition is not met, a new row is inserted into the target table.
+In the ``MATCHED`` case, the ``UPDATE`` column value expressions can depend on any field of the target or the source.
+In the ``NOT MATCHED`` case, the ``INSERT`` expressions can depend on any field of the source.
+
+The ``MERGE`` command requires each target row to match at most one source row. An exception is raised when a single target table row matches more than one source row.
+If a source row is not matched by the ``WHEN`` clause and there is no ``WHEN NOT MATCHED`` clause, the source row is ignored.
+
+The ``MERGE`` statement is commonly used to integrate data from two tables with different contents but similar structures.
+For example, the source table could be part of a production transactional system, while the target table might be located in a data warehouse for analytics.
+Regularly, MERGE operations are performed to update the analytics warehouse with the latest production data.
+You can also use MERGE with tables that have different structures, as long as you can define a condition to match the rows between them.
+
+MERGE Command Privileges
+------------------------
+
+The ``MERGE`` statement does not have a dedicated privilege. Instead, executing a ``MERGE`` statement requires the privileges associated with the individual actions it performs:
+
+* ``UPDATE`` actions: require the ``UPDATE`` privilege on the target table columns referenced in the ``SET`` clause.
+* ``INSERT`` actions: require the ``INSERT`` privilege on the target table.
+
+Each privilege must be granted to the user executing the ``MERGE`` command, based on the specific operations included in the statement.
+
+Example
+-------
+
+Update the sales information for existing products and insert the sales information for the new products in the market.
+
+.. code-block:: text
+
+    MERGE INTO product_sales AS s
+        USING monthly_sales AS ms
+        ON s.product_id = ms.product_id
+    WHEN MATCHED THEN
+        UPDATE SET
+            sales = sales + ms.sales
+          , last_sale = ms.sale_date
+          , current_price = ms.price
+    WHEN NOT MATCHED THEN
+        INSERT (product_id, sales, last_sale, current_price)
+        VALUES (ms.product_id, ms.sales, ms.sale_date, ms.price)
+
+Limitations
+-----------
+
+Any connector can be used as a source table for a ``MERGE`` statement.
+Only connectors which support the ``MERGE`` statement can be the target of a merge operation.
+See the :doc:`connector documentation </connector/>` for more information.
+The ``MERGE`` statement is currently supported only by the iceberg connector.