Improve docs for MERGE

docs/src/main/sphinx/sql/merge.md

@@ -31,28 +31,36 @@ WHEN NOT MATCHED [ AND condition ]
 Conditionally update and/or delete rows of a table and/or insert new
 rows into a table.
 
-`MERGE` supports an arbitrary number of `WHEN` clauses with different
-`MATCHED` conditions, executing the `DELETE`, `UPDATE` or `INSERT`
-operation in the first `WHEN` clause selected by the `MATCHED`
-state and the match condition.
+`MERGE`changes data in the `target_table` based on the contents of the
+`source_table`. The `search_condition` defines a condition, such as a relation
+from identical columns, to associate the source and target data.
 
-For each source row, the `WHEN` clauses are processed in order.  Only
-the first first matching `WHEN` clause is executed and subsequent clauses
-are ignored.  A `MERGE_TARGET_ROW_MULTIPLE_MATCHES` exception is
-raised when a single target table row matches more than one source row.
+`MERGE` supports an arbitrary number of `WHEN` clauses. `MATCHED` conditions can
+execute `DELETE` or `UPDATE` operations on the target data, while `NOT MATCHED`
+conditions can add data from the source to the target table with `INSERT`.
+Additional conditions can narrow down the affected rows.
 
-If a source row is not matched by any `WHEN` clause and there is no
-`WHEN NOT MATCHED` clause, the source row is ignored.
+For each source row, the `WHEN` clauses are processed in order. Only the first
+matching `WHEN` clause is executed and subsequent clauses are ignored. The query
+fails if a single target table row matches more than one source row.
 
 In `WHEN` clauses with `UPDATE` operations, the column value expressions
-can depend on any field of the target or the source.  In the `NOT MATCHED`
+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.
 
+Typical usage of `MERGE` involves two tables with similar structure, containing
+different data. For example, the source table is part of a transactional usage
+in a production system, while the target table is located in a data warehouse
+used for analytics. Periodically, `MERGE` operations are run to combine recent
+production data with long-term data in the analytics warehouse. As long as you
+can define a search condition between the two tables, you can also use very
+different tables.
+
 ## Examples
 
 Delete all customers mentioned in the source table:
 
-```
+```sql
 MERGE INTO accounts t USING monthly_accounts_update s
     ON t.customer = s.customer
     WHEN MATCHED
@@ -62,7 +70,7 @@ MERGE INTO accounts t USING monthly_accounts_update s
 For matching customer rows, increment the purchases, and if there is no
 match, insert the row from the source table:
 
-```
+```sql
 MERGE INTO accounts t USING monthly_accounts_update s
     ON (t.customer = s.customer)
     WHEN MATCHED
@@ -73,12 +81,11 @@ MERGE INTO accounts t USING monthly_accounts_update s
 ```
 
 `MERGE` into the target table from the source table, deleting any matching
-target row for which the source address is Centreville.  For all other
-matching rows, add the source purchases and set the address to the source
-address, if there is no match in the target table, insert the source
-table row:
+target row for which the source address is `Centreville`. For all other matching
+rows, add the source purchases and set the address to the source address. If
+there is no match in the target table, insert the source table row:
 
-```
+```sql
 MERGE INTO accounts t USING monthly_accounts_update s
     ON (t.customer = s.customer)
     WHEN MATCHED AND s.address = 'Centreville'