When an Apache Iceberg append adds one file, which metadata files are written?

## What an append actually produces Iceberg metadata is a tree of immutable files, and a commit is a **copy-on-write of the path from the root to the change**. For an append of one data file, the writer produces, in order: 1. **The data file** — e.g. `data/ts_day=2026-05-01/00000-7-b41c9e2f.parquet`, written and closed before any metadata is touched. 2. **A manifest** — `b41c9e2f-m0.avro`, one `manifest_entry` with `status = 1` (ADDED), `snapshot_id` set to the new snapshot, and a `data_file` struct carrying `file_path`, `file_format`, the `partition` tuple, `record_count`, `file_size_in_bytes` and the column stats (`value_counts`, `null_value_counts`, `lower_bounds`, `upper_bounds`). 3. **A manifest list** — `snap-<new-snapshot-id>-1-<uuid>.avro`. This is the file people misjudge: it lists the *new* manifest **and re-references the parent snapshot's manifests by path**. Those older manifests are not read, not copied, not rewritten — only their paths and summary rows are carried forward. 4. **A metadata file** — a fresh `*.metadata.json` identical to the previous one except that `snapshots` gains an entry (with `snapshot-id`, `parent-snapshot-id`, `sequence-number`, `timestamp-ms`, `schema-id`, `manifest-list`, and a `summary` map recording `operation: append` plus added/total counts), `current-snapshot-id` moves, and `snapshot-log` and `metadata-log` gain rows. 5. **The commit** — the catalog is asked to move the table's current-metadata pointer from the base metadata file to the new one, atomically. Until that swap succeeds the new files exist but are unreachable; if it fails, they are orphans and no reader ever saw them. ## What is *not* written No existing data file is touched. No existing manifest is modified — Avro manifests are write-once. The previous metadata JSON, manifest list and manifests all remain on storage and remain valid, which is precisely what makes the parent snapshot still readable. Time travel is not a replay mechanism; it is the fact that the older root is still intact and still points at intact children. This structure explains the cost model: **a commit's metadata write is proportional to what changed, not to table size.** Appending one file to a table with a million files writes one small manifest and one manifest list whose row count equals the number of manifests — not the number of files. ## The manifest-merge nuance If every append wrote a brand-new manifest and nothing ever consolidated them, a table committing every minute would accumulate thousands of tiny manifests and planning would slow down. Iceberg counters this at commit time: `commit.manifest-merge.enabled` (on by default for merge appends) lets a commit combine small manifests into larger ones, governed by `commit.manifest.target-size-bytes` and `commit.manifest.min-count-to-merge`. So the honest answer is "a new manifest, a new manifest list and a new metadata file — and possibly some small manifests merged". Streaming writers that want the cheapest possible commit use a **fast append**, which skips merging entirely and accepts more manifests, leaving consolidation to a later maintenance job. ## Sequence numbers From format version 2, each snapshot receives a monotonically increasing `sequence-number`, and manifest entries inherit it. This is not decoration: it orders commits and determines which delete files apply to which data files. An appended data file with a high sequence number is unaffected by delete files committed earlier, which is what makes concurrent append-plus-delete workloads correct. ## Other operation types - **Overwrite / delete / MERGE** follow the same shape, but the new manifest contains entries with `status = 2` (DELETED) for removed files, and in v2+ may add a **delete manifest** (`content = 1` in the manifest list) referencing position or equality delete files. - **Schema or partition-spec change** may write only a new metadata JSON — a new schema in `schemas` or a new spec in `partition-specs`, with no snapshot at all, because no data changed. - **Rewrites (compaction)** produce a snapshot that adds new files and marks old ones deleted; the old files stay on storage until snapshot expiry releases them. ## The takeaway to say out loud "A commit rewrites the root and one branch of the metadata tree, and re-references everything else." That single sentence carries the atomicity story (one pointer swap), the time-travel story (old roots intact), the performance story (write cost tracks change size), and the storage story (old files linger until a retention job removes them).