docs: enforce merge-on-read for append-only Iceberg sinks (#929)

* Initial plan

* docs: document append-only Iceberg sinks require merge-on-read write mode

Co-authored-by: hzxa21 <5518566+hzxa21@users.noreply.github.com>

* docs: address code review feedback on write mode docs

Co-authored-by: hzxa21 <5518566+hzxa21@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: hzxa21 <5518566+hzxa21@users.noreply.github.com>

Author: Copilot

iceberg/deliver-to-iceberg.mdx

@@ -48,6 +48,7 @@ WITH (
 | `database.name` | Yes | The name of the target Iceberg database. |
 | `table.name`| Yes| The name of the target Iceberg table.|
 | `primary_key`| Yes, if `type` is `upsert` | A comma-separated list of columns that form the primary key. |
+| `write_mode` | No | Write mode for the sink. Options: `'merge-on-read'` (default) or `'copy-on-write'`. **Important:** Copy-on-write is only supported for upsert sinks. Append-only sinks must use merge-on-read. See [Write modes](/iceberg/write-modes) for details. |
 | `force_append_only`| No | If `true`, converts an `upsert` stream to `append-only`. Updates become inserts and deletes are ignored. Default: `false`. |
 | `is_exactly_once`| No | Set to `true` to enable exactly-once delivery semantics. This provides stronger consistency but may impact performance. Default: `true`. <br/><br/> Exactly-once delivery requires [sink decoupling](/delivery/overview#sink-decoupling) to be enabled (the default behavior). If you `SET sink_decouple = false;`, exactly-once semantics will be automatically disabled for the sink.|
 | `commit_checkpoint_interval`| No | Controls how often RisingWave commits to Iceberg. Default: `60` (about every 60 seconds in the default configuration). |

iceberg/write-modes.mdx

@@ -13,7 +13,7 @@ RisingWave supports two write modes for Iceberg sinks and tables, allowing you t
 
 In merge-on-read mode, updates and deletes are written to separate delta files (delete files) instead of rewriting existing data files. When the data is queried, the engine merges the base data files with the delete files on the fly to produce the latest view.
 
-This is the default write mode in RisingWave.
+This is the default write mode in RisingWave and is **required** for append-only sinks and tables.
 
 ### How it works
 
@@ -59,6 +59,10 @@ WITH (
 
 ## Copy-on-write (CoW)
 
+<Warning>
+Copy-on-write mode is **only supported for upsert sinks and tables**. Append-only sinks must use merge-on-read mode. Attempting to create an append-only sink with `write_mode = 'copy-on-write'` will result in an error.
+</Warning>
+
 In copy-on-write mode, updates and deletes are handled by rewriting the data files that contain the affected rows. This ensures that every snapshot presents a clean, delete-free view of the data, optimizing read performance for external consumers.
 
 ### How it works
@@ -114,12 +118,18 @@ WITH (
 
 Choose the write mode that best fits your workload and query patterns.
 
+<Note>
+**For append-only workloads**: Merge-on-read is required as it is strictly better than copy-on-write for append-only data. Copy-on-write provides no benefit when there are no updates or deletes to eagerly compact, and has worse write performance.
+</Note>
+
 *   **Use Merge-on-Read (MoR) if**:
     *   Your primary concern is write performance and low ingestion latency.
     *   Downstream query engines can efficiently process delete files.
     *   Workloads are write-heavy with frequent updates or deletes.
+    *   Your sink is append-only (required for append-only sinks).
 
 *   **Use Copy-on-Write (CoW) if**:
+    *   Your sink or table is upsert (not available for append-only).
     *   Your primary concern is read performance.
     *   Downstream consumers do not efficiently handle delete files.
     *   You can tolerate higher write amplification and ingestion latency.
@@ -129,10 +139,11 @@ Choose the write mode that best fits your workload and query patterns.
 
 | Feature | Merge-on-Read (MoR) | Copy-on-Write (CoW) |
 |---|---|---|
+| **Supported for** | Append-only and upsert sinks/tables | Upsert sinks/tables only |
 | **Primary goal** | Optimize write performance | Optimize read performance |
 | **Write amplification** | Low (writes delta files) | High (data files are rewritten) |
 | **Read performance** | Slower (requires merging data and delete files) | Faster (no merge needed at read time) |
 | **Ingestion latency** | Lower (writes are faster) | Higher (due to compaction) |
 | **Storage overhead** | Higher (stores base and delta files) | Lower (no separate delete files) |
 | **Default mode** | Yes | No |
-| **Ideal for** | Write-heavy workloads, real-time ingestion | Read-heavy workloads, BI dashboards |
+| **Ideal for** | Write-heavy workloads, real-time ingestion, append-only data | Read-heavy upsert workloads, BI dashboards |