Copy-on-Write vs Merge-on-Read

## The same first step Whatever the table type, an Apache Hudi upsert starts identically: the incoming records are tagged. Hudi consults its index with each record key to find which **file group** — a stable, file-ID-identified set of records inside a partition — already holds that key. Records that match an existing file group are updates; the rest are inserts. Only after tagging does the table type decide what physically gets written. ## Copy-on-Write: rewrite the base file In a `COPY_ON_WRITE` table each file group version is a single Parquet **base file**. For every file group that received at least one update, the writer streams the existing base file, merges the incoming records into that stream (the precombine field breaks ties between two records with the same key), and writes a brand-new base file for the group. File groups no record landed in are not touched at all. On success Hudi appends a completed `commit` instant to the timeline in `.hoodie`; before that instant exists, the new files are invisible, which is what makes the write atomic. The read side is then trivial: pick the newest base file per file group and read Parquet. The cost sits entirely on the writer, and it is proportional to the *bytes* in the touched files rather than to the number of changed rows. ## Merge-on-Read: append a log block In a `MERGE_ON_READ` table a file group version — a **file slice** — is a base file *plus zero or more log files*. An update is not merged into the base file. Instead the writer appends the records as blocks into a log file associated with that file group and that base instant; log blocks are Avro-encoded by default, and a delete arrives as a delete block rather than a rewritten row. The commit is recorded as a `deltacommit` instant, a distinct action name from CoW's `commit`, so you can tell from the timeline alone which path a write took. No large Parquet file is read or rewritten, so ingestion latency drops sharply and write amplification largely disappears. Two costs replace it: - **Read cost.** A snapshot query over the table must now open the base file *and* replay its log blocks, merging by record key in memory, before it can return rows. The more log files accumulate on a slice, the slower and more memory-hungry that merge becomes. - **Compaction.** A background job must periodically read a file slice's base file plus its logs and write a new base file, producing a fresh file slice with no logs. Compaction is scheduled as a `compaction` instant and lands as a `commit` when it completes. Until it runs, the read cost keeps growing. ## Reading the difference off the directory listing A Copy-on-Write partition contains only `.parquet` base files. A Merge-on-Read partition contains base files plus hidden log files whose names carry the same file ID as the base file they belong to. If you see log files, the table is Merge-on-Read and there is unmerged data on disk; if the timeline shows `deltacommit` instants, the same conclusion follows. ## Delete handling Under Copy-on-Write a delete is just another merge input: the row is dropped while the base file is rewritten, so the file that comes out no longer contains it. Under Merge-on-Read a delete is a delete block appended to a log file — the row is still physically present in the base file, and only the merge at read time (or the next compaction) removes it from results. This is why a Merge-on-Read table can look like it "still returns deleted rows" to a reader using the wrong query type. ## Do not cross the wires Two naming traps are worth calling out. First, Hudi's Merge-on-Read is a *table type* covering every write to the table — it is not the same thing as a per-operation write mode chosen for a single DML statement in other table formats. Second, Hudi's log files are its own append log format carrying record-level blocks; they are not equivalent to a positional delete file or a bitmap of deleted row positions. Hudi merges by *record key*, which is why a record key and a precombine field are mandatory concepts in Hudi and optional or absent elsewhere. ## Choosing between them Copy-on-Write suits batch-loaded tables read far more than written: you pay once at load and every query is fast. Merge-on-Read suits streaming and CDC ingestion where commits arrive every few minutes and updates are scattered: you pay a little on every read and you must operate compaction as a real, monitored service. The wrong pairing is what produces the two classic incidents — hour-long batch upserts on a CoW table with scattered keys, and steadily degrading queries on a MoR table whose compaction stopped.