Watermark

Wat is een watermark?

Een watermark is een marker die bijhoudt tot waar data al verwerkt is. Dat kan een tijdstip zijn, een oplopende ID, een bestandsnaam, een batchnummer of een eventpositie in een stream.

Watermarks worden vooral gebruikt bij incrementele ladingen. Ze geven de pipeline geheugen: "tot hier ben ik geraakt, vanaf hier moet ik de volgende keer verder".

Een goede watermark voorkomt dat je records mist of dubbel verwerkt. Dat klinkt eenvoudig, maar wordt snel subtiel bij late updates, tijdzones, fouten halverwege en parallelle verwerking.

Voorbeelden van watermarks

Datum-watermark
De pipeline bewaart de hoogste verwerkte `updated_at`. De volgende run leest records die later gewijzigd zijn.

ID-watermark
De pipeline bewaart de hoogste verwerkte order-ID. Dit werkt alleen wanneer IDs oplopend en betrouwbaar zijn.

Bestandswatermark
Bij dagelijkse bestanden onthoud je welke bestandsdatum of bestandsnaam al verwerkt is.

Stream-offset
Bij streaming data onthoud je tot welke positie in de eventstream je geraakt bent.

Wanneer gebruik je een watermark?

1. Bij incrementele lading. De watermark bepaalt welke records de volgende run moet ophalen.

2. Bij API-synchronisatie. Je vermijdt dat je telkens alle pagina's opnieuw moet lezen.

3. Bij bestandsimports. Je weet welke bestanden al verwerkt zijn.

4. Bij eventverwerking. Je houdt bij welke events al afgehandeld zijn.

Voorbeeld

Een pipeline leest facturen uit een API. Na een succesvolle run bewaart ze `2026-07-08T02:15:00` als watermark, omdat dat de hoogste verwerkte wijzigingsdatum was. De volgende run vraagt facturen op met `updated_at` groter dan dat tijdstip.

Om late updates op te vangen, leest de pipeline telkens vijf minuten overlap opnieuw. Dankzij idempotentie worden records in die overlap bijgewerkt in plaats van dubbel toegevoegd.

Waar moet je op letten?

Werk de watermark niet te vroeg bij
Als je de watermark opslaat voordat alle records succesvol verwerkt zijn, kan een fout ervoor zorgen dat je data overslaat.

Gebruik overlap waar nodig
Bronnen kunnen records met vertraging aanleveren. Een kleine overlap maakt de pipeline robuuster, zolang de verwerking idempotent is.

Let op tijdzones
Een timestamp zonder tijdzone veroorzaakt makkelijk gaten of dubbels rond zomeruur, winteruur en servers in andere regio's.

Deletes vragen extra aandacht
Een watermark op `updated_at` ziet niet automatisch dat een record uit de bron verwijderd is, tenzij de bron deletes registreert.

Watermark versus checkpoint

De termen worden soms door elkaar gebruikt. Een watermark gaat meestal over de inhoudelijke voortgang in de data: tot welke datum, ID of offset is verwerkt. Een checkpoint is breder en kan ook technische toestand bevatten, zoals tijdelijke bestanden, jobstatus of partitievoortgang.

In de praktijk maakt de naam minder uit dan de afspraak: wat wordt precies bewaard, wanneer wordt het bijgewerkt en hoe herstel je na een fout?

Verwant aan en niet verwarren met

Incrementele lading
De incrementele lading is het proces. De watermark is het geheugen van dat proces.

Idempotentie
Idempotentie maakt het veilig om een stuk rond de watermark opnieuw te verwerken.

Streaming data
Bij streaming lijkt een watermark vaak op een offset of voortgangspositie in de eventstroom.

Data lineage
Data lineage toont waar data vandaan kwam en welke stappen ze volgde. Een watermark is operationele metadata binnen zo'n stap.

FAQ over watermarks

1. Is een watermark altijd een timestamp?
Nee. Het kan elke marker zijn die betrouwbaar voortgang aangeeft.

2. Waar bewaar je een watermark?
In een controle- of metadatatabel, orchestrator, state store of pipelineconfiguratie. Bewaar ze niet alleen in logs.

3. Wat als de watermark fout staat?
Dan heb je een herstelactie nodig, zoals een backfill vanaf een vroeger punt of een volledige reload van de getroffen periode.