Upsert

Wat is een upsert?

Een upsert is een combinatie van insert en update. De databank voegt een rij toe als ze nog niet bestaat. Bestaat ze al, dan werkt de databank de bestaande rij bij.

Dat is handig in datapijplijnen. Je haalt elke nacht klanten uit een CRM. Nieuwe klanten moeten erbij, bestaande klanten moeten hun gewijzigde naam, status of e-mailadres krijgen. Je wil niet eerst met losse code uitzoeken welke rij nieuw is en welke niet. De databank kan dat zelf beslissen op basis van een sleutel.

Een upsert maakt herhalen veiliger. Draait dezelfde lading per ongeluk twee keer, dan krijg je niet twee keer dezelfde klant, maar dezelfde eindtoestand.

Hoe ziet een upsert eruit in SQL?

In PostgreSQL gebruik je INSERT ... ON CONFLICT. De conflictregel verwijst naar een unieke sleutel of primaire sleutel.

INSERT INTO customers (customer_id, name, email, updated_at)
VALUES (42, 'Acme NV', 'finance@acme.example', now())
ON CONFLICT (customer_id)
DO UPDATE SET
  name = EXCLUDED.name,
  email = EXCLUDED.email,
  updated_at = EXCLUDED.updated_at;

EXCLUDED verwijst naar de rij die je probeerde in te voegen. Bestond customer_id = 42 nog niet, dan komt de rij erbij. Bestond ze wel, dan neemt de bestaande rij de nieuwe waarden over.

Wanneer gebruik je een upsert?

• Bij incrementele ladingen. Je verwerkt alleen nieuwe en gewijzigde bronrecords, niet telkens de volledige tabel.

• Bij API-synchronisatie. Een CRM, webshop of boekhoudpakket stuurt dezelfde entiteit vaker door. De doeldata moet bijblijven, niet verdubbelen.

• Bij retry-logica. Als een stap opnieuw draait na een tijdelijke fout, wil je dezelfde eindtoestand behouden.

• Bij staging naar warehouse. Je laadt brondata eerst ruw en verwerkt daarna wijzigingen naar een nette doeltabel.

Upsert versus insert, update en merge

Een gewone insert voegt altijd een nieuwe rij toe. Een update wijzigt alleen bestaande rijen. Een upsert kiest tussen die twee op basis van een conflictregel.

Veel databases hebben ook MERGE. Dat is breder: je vergelijkt een bronset met een doeltabel en kan inserts, updates en soms deletes in één statement doen. Een upsert is de smalle, vaak eenvoudigere variant voor een rij of set rijen waar de sleutel het verschil maakt.

Waar moet je op letten bij het gebruik van upsert

• Je hebt een betrouwbare sleutel nodig. Zonder primaire of unieke sleutel weet de databank niet wanneer iets hetzelfde record is.

• Niet elke kolom moet overschreven worden. Soms wil je alleen bronvelden bijwerken en lokale verrijkingen bewaren.

• Deletes zijn een apart verhaal. Een upsert verwerkt nieuwe en gewijzigde rijen. Verdwenen rijen uit de bron moet je met een andere regel afhandelen.

• Let op volgorde bij events. Een oud event mag geen nieuwere status overschrijven. Gebruik waar nodig een tijdstip of versienummer in de updatevoorwaarde.

FAQ over upserts

1. Is een upsert idempotent?
Vaak wel, als de sleutel en updatevoorwaarde goed gekozen zijn. Dezelfde input opnieuw verwerken geeft dan dezelfde eindtoestand.

2. Werkt upsert in elke database hetzelfde?
Nee. PostgreSQL gebruikt ON CONFLICT, MySQL heeft ON DUPLICATE KEY UPDATE, en andere systemen gebruiken vaak MERGE.

3. Kan een upsert records verwijderen?
Nee, niet op zichzelf. Voor verwijderingen gebruik je soft deletes, hard deletes of een aparte synchronisatiestap.