Improve developer docs for connector MERGE support

core/trino-main/src/main/java/io/trino/operator/MergeRowChangeProcessor.java

@@ -31,6 +31,7 @@ public interface MergeRowChangeProcessor
      * <ul>
      *     <li>All data columns, in table column order</li>
      *     <li>{@link ConnectorMergeSink#storeMergedRows The operation block}</li>
+     *     <li>{@link ConnectorMergeSink#storeMergedRows The merge case number block}</li>
      *     <li>The rowId block</li>
      *     <li>The last column in the resulting page is 1 if the row is an insert
      *         derived from an update, and zero otherwise.</li>

core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMergeSink.java

@@ -51,15 +51,17 @@ public interface ConnectorMergeSink
     /**
      * Store the page resulting from a merge. The page consists of {@code n} channels, numbered {@code 0..n-1}:
      * <ul>
-     *     <li>Blocks {@code 0..n-3} in page are the data columns</li>
-     *     <li>Block {@code n-2} is the tinyint <i>operation</i>:
+     *     <li>Blocks {@code 0..n-4} in page are the data columns</li>
+     *     <li>Block {@code n-3} is the tinyint <i>operation</i>:
      *     <ul>
      *         <li>{@link #INSERT_OPERATION_NUMBER}</li>
      *         <li>{@link #DELETE_OPERATION_NUMBER}</li>
      *         <li>{@link #UPDATE_OPERATION_NUMBER}</li>
      *         <li>{@link #UPDATE_INSERT_OPERATION_NUMBER}</li>
      *         <li>{@link #UPDATE_DELETE_OPERATION_NUMBER}</li>
      *     </ul>
+     *     <li>Block {@code n-2} is the integer <i>merge case number</i>:
+     *     <p>the number starting with 0, for the `WHEN` clause that matched for the row</p>
      *     <li>Block {@code n-1} is a connector-specific rowId column, whose handle was previously returned by
      *         {@link ConnectorMetadata#getMergeRowIdColumnHandle(ConnectorSession, ConnectorTableHandle) getMergeRowIdColumnHandle()}
      *     </li>

docs/src/main/sphinx/develop/supporting-merge.md

@@ -233,15 +233,16 @@ The merge case `RowBlock` has the following layout:
 - A block containing the `MERGE` case operation number, encoded as
   `INSERT` = 1, `DELETE` = 2, `UPDATE` = 3 and if no `MERGE`
   case matched, -1.
-- A block containing the number, starting with 0, for the
+- A block containing the `MERGE` case number, the number starting with 0, for the
   `WHEN` clause that matched for the row, or -1 if no clause
   matched.
 
 The page returned from `transformPage` consists of:
 
 - All table columns, in table column order.
-- The merge case operation block.
-- The rowId block.
+- The tinyint type merge case operation block.
+- The integer type merge case number block.
+- The rowId block remains unchanged from the provided input page.
 - A byte block containing 1 if the row is an insert derived from an
   update operation, and 0 otherwise. This block is used to correctly
   calculate the count of rows changed for connectors that represent
@@ -309,7 +310,8 @@ The only interesting methods are:
   `ConnectorPageSinkProvider.createMergeSink()`, passing the page
   generated by the `RowChangeProcessor.transformPage()` method.
   That page consists of all table columns, in table column order,
-  followed by the `TINYINT` operation column, followed by the rowId column.
+  followed by the `TINYINT` operation column, followed by the `INTEGER`
+  merge case number column, followed by the rowId column.
 
   The job of `storeMergedRows()` is iterate over the rows in the page,
   and process them based on the value of the operation column, `INSERT`,