From 84417d914b054571441e69ae9e445372ac6c8419 Mon Sep 17 00:00:00 2001
From: chenjian2664 <chenjian2664@gmail.com>
Date: Mon, 6 Jan 2025 16:05:58 +0800
Subject: [PATCH] Improve developer docs for connector MERGE support

---
 .../io/trino/operator/MergeRowChangeProcessor.java     |  1 +
 .../io/trino/spi/connector/ConnectorMergeSink.java     |  6 ++++--
 docs/src/main/sphinx/develop/supporting-merge.md       | 10 ++++++----
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/core/trino-main/src/main/java/io/trino/operator/MergeRowChangeProcessor.java b/core/trino-main/src/main/java/io/trino/operator/MergeRowChangeProcessor.java
index 67f0df051bb7..970822f9b8ab 100644
--- a/core/trino-main/src/main/java/io/trino/operator/MergeRowChangeProcessor.java
+++ b/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>
diff --git a/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMergeSink.java b/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMergeSink.java
index b3887e4bce07..a01bf23b199f 100644
--- a/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMergeSink.java
+++ b/core/trino-spi/src/main/java/io/trino/spi/connector/ConnectorMergeSink.java
@@ -51,8 +51,8 @@ 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>
@@ -60,6 +60,8 @@ public interface ConnectorMergeSink
      *         <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>
diff --git a/docs/src/main/sphinx/develop/supporting-merge.md b/docs/src/main/sphinx/develop/supporting-merge.md
index b33d2b5e1f4c..40d8ef506fc1 100644
--- a/docs/src/main/sphinx/develop/supporting-merge.md
+++ b/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`,