Explain the internal working of automatic tag creation with a watermark?

Watermark-based automatic tagging lets Paimon create tags aligned to event time rather than wall-clock commit time, which matters for streaming pipelines where records can arrive late.

flowchart TD
    A["Streaming writer commits new snapshot"] --> B["Snapshot records its watermark (max event-time seen so far)"]
    B --> C{"Watermark crosses next tag boundary? e.g. next full hour"}
    C -- "No" --> A
    C -- "Yes" --> D["Paimon creates a tag pointing at the snapshot whose watermark first crossed the boundary"]
    D --> E["Tag's files protected from expiration per tag retention policy"]
    E --> F{"Retention window exceeded?"}
    F -- "Yes" --> G["Old tag automatically deleted"]
    F -- "No" --> E

Concretely: every snapshot a streaming writer commits carries a watermark, the maximum event-time timestamp observed so far. Paimon periodically checks whether that watermark has crossed the next configured tag interval boundary (say, the top of the next hour). The moment it does, Paimon creates a tag on the snapshot responsible for that crossing — not necessarily the very latest snapshot, but the one whose watermark first satisfied the boundary.

This produces tags that line up with real-world event time (useful for "give me exactly the data as of 2pm event time" queries) rather than tags that line up with whenever a batch job happened to run. Retention settings then control how many such tags are kept before older ones are automatically deleted.