Parcourir les aide-mémoire · Ingénierie des données

Technologie: Ingénierie des donnéesCatégorie: Intégration de donnéesNiveau: IntermédiaireMis à jour

Modèles de chargement incrémental

Concevez des chargements incrémentaux sûrs avec des watermarks, la CDC, des high-water marks, MERGE, des écritures idempotentes, la gestion des données tardives et des checkpoints rejouables, sans sauter ni dupliquer de données.

Sur cette page
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Référence : le rechargement complet
  5. 2. High-water mark avec un ID croissant
  6. 3. Ne supposez pas que tout ID est un high-water mark valide
  7. 4. Watermark sur horodatage
  8. 5. Horodatage + critère de départage unique
  9. 6. Le critère de départage doit correspondre à l’ordre de tri
  10. 7. N’utilisez pas MAX(updated_at) seul sans penser aux égalités
  11. 8. Fenêtres de lot semi-ouvertes
  12. 9. Les fenêtres semi-ouvertes ne règlent pas les arrivées tardives
  13. 10. Fenêtres de chevauchement pour les arrivées tardives
  14. 11. Exemple de chevauchement glissant
  15. 12. Persistez le checkpoint après le succès
  16. 13. Le checkpoint doit décrire le périmètre terminé
  17. 14. Conservez l’état du checkpoint de façon durable
  18. 15. Utilisez un checkpoint par flux logique
  19. 16. Chargement incrémental par manifeste de fichiers
  20. 17. Le nom de fichier seul ne prouve pas l’unicité
  21. 18. Le partitionnement par chemin de fichier peut simplifier la découverte incrémentale
  22. 19. Modèle CDC
  23. 20. CDC ne signifie pas automatiquement streaming
  24. 21. Utilisez la séquence, le LSN ou la version natifs de la source lorsqu’ils existent
  25. 22. Ne convertissez pas un checkpoint natif de la source en horodatage moins fiable
  26. 23. Modèle de comparaison d’instantanés (snapshot diff)
  27. 24. Modèle de comparaison par hachage (hash-diff)
  28. 25. Ne hachez que les colonnes pertinentes
  29. 26. Normalisez les valeurs avant le hachage
  30. 27. MERGE pour les insertions et les mises à jour
  31. 28. Utilisez des correspondances explicites pour un MERGE maîtrisé
  32. 29. Ne mettez à jour que lorsque la source est plus récente
  33. 30. Validez l’unicité de la source du MERGE
  34. 31. Dédupliquez l’entrée incrémentale de manière déterministe
  35. 32. Ajout incrémental pour les événements immuables
  36. 33. L’ajout nécessite quand même une stratégie contre les doublons
  37. 34. Les suppressions exigent une conception explicite
  38. 35. Modèle de suppression logique (soft delete)
  39. 36. Évitez la réconciliation des suppressions source/cible sur des extractions partielles
  40. 37. La réconciliation d’instantanés peut détecter les suppressions
  41. 38. Écrasement incrémental de partitions
  42. 39. N’écrasez pas toute la table pour le changement d’une seule partition
  43. 40. Les chargements incrémentaux ont besoin d’idempotence
  44. 41. Les travaux en ajout seul ont besoin d’une protection contre les doublons lors des nouvelles tentatives
  45. 42. MERGE n’est pas automatiquement idempotent
  46. 43. Gérez avec soin les nouvelles tentatives et le checkpoint
  47. 44. Un état d’esprit proche du commit en deux phases
  48. 45. Persistez les métadonnées des lots
  49. 46. Réconciliez les nombres de lignes
  50. 47. Réconciliez aussi les totaux métier
  51. 48. N’avancez jamais le checkpoint si des contrôles qualité bloquants échouent
  52. 49. Distinguez les contrôles qualité d’avertissement des contrôles bloquants
  53. 50. Modèle pour les données tardives
  54. 51. Un backfill ne doit pas corrompre le checkpoint en production
  55. 52. Le backfill doit être explicite
  56. 53. Le backfill peut réutiliser la même logique de transformation
  57. 54. Protégez-vous du chevauchement des écritures de production et de backfill
  58. 55. Staging avant MERGE
  59. 56. Attribuez un ID de lot aux données de staging
  60. 57. Ne videz pas un staging partagé à la légère
  61. 58. Les mises à jour de la source peuvent arriver dans le désordre
  62. 59. L’heure d’ingestion n’indique pas la récence côté source
  63. 60. L’ordre des mises à jour CDC compte
  64. 61. Les lectures incrémentales sur l’heure d’événement sont risquées pour les entités modifiables
  65. 62. Un watermark sur la date de création convient aux entités en ajout seul
  66. 63. Utilisez l’heure de commit de la source lorsqu’elle est disponible
  67. 64. Le décalage d’horloge peut casser les watermarks sur horodatage
  68. 65. Évitez d’utiliser current_timestamp() comme watermark de la source
  69. 66. Fixez la borne du lot avant la lecture de la source
  70. 67. Utilisez des bornes décalées lorsque les commits de la source se stabilisent tardivement
  71. 68. Pagination et chargement incrémental sont deux choses différentes
  72. 69. Conservez le curseur de pagination jusqu’à la fin de l’extraction bornée
  73. 70. Exemple d’extraction incrémentale depuis une API
  74. 71. Les curseurs d’API peuvent expirer
  75. 72. Les limites de débit influencent la conception du chargement incrémental
  76. 73. Le chargement incrémental doit pouvoir reprendre
  77. 74. Persistez le périmètre de l’échec
  78. 75. Ne modifiez pas les checkpoints manuellement à la légère
  79. 76. Réparer un checkpoint est un changement de production
  80. 77. Les chargements incrémentaux ont besoin d’observabilité
  81. 78. Une absence soudaine de changements peut être suspecte
  82. 79. Un volume de changements soudainement énorme peut être suspect
  83. 80. Monotonie du checkpoint
  84. 81. Alignez le périmètre du checkpoint sur le filtre de la source
  85. 82. La dérive de schéma peut casser les chargements incrémentaux en silence
  86. 83. Changer de champ de watermark est une migration
  87. 84. Changer la clé du MERGE est dangereux
  88. 85. La logique incrémentale doit être déterministe
  89. 86. Modèle incrémental SCD Type 1
  90. 87. Modèle incrémental SCD Type 2
  91. 88. SCD Type 2 exige de la rigueur sur les doublons et les versions
  92. 89. Les chargements de faits par instantané peuvent utiliser le remplacement de partitions
  93. 90. Les chargements de faits d’audit utilisent souvent l’ajout
  94. 91. Séparez le checkpoint d’ingestion du checkpoint de transformation si nécessaire
  95. 92. Des checkpoints par couche peuvent améliorer la reprise
  96. 93. La progression du checkpoint fait partie de la fraîcheur
  97. 94. Les lectures incrémentales doivent être bornées lorsque c’est possible
  98. 95. Une extraction bornée permet des nouvelles tentatives reproductibles
  99. 96. Une stratégie de reconstruction doit exister
  100. 97. L’incrémental est une optimisation, pas la source de vérité
  101. 98. Testez les scénarios d’échec
  102. 99. Utilisez une liste de vérification de mise en œuvre reproductible
  103. Interpréter le résultat
  104. Points à vérifier
  105. Des lignes manquent après un redémarrage
  106. Des lignes en double apparaissent
  107. D’anciennes valeurs écrasent des valeurs plus récentes
  108. Les suppressions n’atteignent jamais la cible
  109. Le travail incrémental relit soudain tout
  110. Le travail lit zéro ligne de manière inattendue
  111. Notes de production
  112. Les checkpoints sont des données de production
  113. C’est l’idempotence qui rend les nouvelles tentatives sûres
  114. Les horodatages de la source ne sont pas toujours fiables
  115. Les données tardives sont normales dans les systèmes distribués
  116. Les suppressions exigent une sémantique explicite
  117. Les backfills font partie de l’architecture
  118. Erreurs fréquentes
  119. 1. Utiliser MAX(updated_at) comme unique checkpoint
  120. 2. Avancer le checkpoint avant la réussite de l’écriture
  121. 3. Supposer que MERGE rend chaque nouvelle tentative sûre
  122. 4. Utiliser la date de création pour des enregistrements modifiables
  123. 5. Ignorer les suppressions
  124. 6. Traiter l’heure d’ingestion comme une version de la source
  125. 7. Modifier manuellement les watermarks sans plan de rejeu
  126. 8. Laisser les backfills modifier les checkpoints de production
  127. 9. Utiliser le seul nom de fichier comme identité de traitement
  128. 10. Ne pas avoir de périmètre borné pour les nouvelles tentatives
  129. Étape suivante
  130. Pour aller plus loin

Problème

Un rechargement complet devient trop coûteux, trop lent ou trop perturbant : le pipeline doit donc ne traiter que les données nouvelles ou modifiées.

La difficulté n’est pas de lire moins de lignes.

Les vrais problèmes d’ingénierie sont les suivants :

  • choisir une limite de changement fiable
  • éviter de sauter des enregistrements
  • éviter les chargements en double
  • gérer les égalités d’horodatage
  • gérer les mises à jour et les suppressions
  • reprendre après un échec
  • prendre en charge les données tardives
  • coordonner les nouvelles tentatives et les rechargements historiques (backfills)
  • maintenir la cohérence entre l’état de la source et celui de la cible

L’objectif est de rendre la limite incrémentale explicite, durable et rejouable.

Réponse rapide

Choisissez le modèle en fonction de ce que la source peut fournir de manière fiable :

La source a un ID croissant immuable
→ high-water mark

La source a un horodatage updated_at fiable
→ watermark sur horodatage + critère de départage déterministe

La source expose la CDC/un flux de changements
→ consommer les enregistrements de changement avec un checkpoint durable

La source livre des fichiers
→ manifeste de fichiers / checkpoint par lot

La source ne peut renvoyer que des instantanés complets
→ comparaison d’instantanés / hash-diff / MERGE via staging

La cible a besoin d’insertions + mises à jour
→ MERGE / upsert

Les suppressions doivent être propagées
→ tombstones CDC ou réconciliation explicite source-cible

La règle la plus importante :

n’avancer le checkpoint qu’après
la réussite de l’écriture dans la cible et de la validation requise

Code / commandes

1. Référence : le rechargement complet

Avant d’introduire la complexité de l’incrémental, vérifiez si une reconstruction complète reste réaliste.

Modèle conceptuel :

lire toute la source
→ transformer
→ valider
→ remplacer la cible

Le rechargement complet est souvent plus simple et plus fiable pour :

  • les petits jeux de données
  • les dimensions à croissance lente
  • les travaux peu fréquents
  • les tables Gold reconstructibles

N’implémentez pas de logique CDC ou de watermark lorsqu’une reconstruction complète sûre coûte peu.


2. High-water mark avec un ID croissant

Supposons que la source garantisse une clé croissante immuable :

order_event_id

Persistez :

last_successful_id = 450000

Requête suivante :

SELECT
    order_event_id,
    order_id,
    event_type,
    event_time
FROM source_order_events
WHERE order_event_id > @last_successful_id
ORDER BY order_event_id;

Après un traitement réussi :

last_successful_id = max(order_event_id traités)

C’est simple et robuste lorsque la source garantit réellement des ID monotones.


3. Ne supposez pas que tout ID est un high-water mark valide

Une clé peut être unique sans être ordonnée.

Exemples :

UUID aléatoire
GUID
hachage
référence externe

N’utilisez pas :

id > last_id

sauf si la source garantit un ordre significatif.


4. Watermark sur horodatage

Modèle courant :

SELECT
    order_id,
    updated_at,
    amount,
    status
FROM source_orders
WHERE updated_at > @last_watermark;

Cela semble simple, mais peut sauter des lignes lorsque plusieurs enregistrements partagent le même horodatage.

Utilisez un critère de départage.


5. Horodatage + critère de départage unique

Persistez :

last_updated_at
last_order_id

Requête :

SELECT
    order_id,
    updated_at,
    amount,
    status
FROM source_orders
WHERE
    updated_at > @last_updated_at
    OR (
        updated_at = @last_updated_at
        AND order_id > @last_order_id
    )
ORDER BY
    updated_at,
    order_id;

Vous obtenez ainsi une reprise déterministe malgré les égalités d’horodatage.


6. Le critère de départage doit correspondre à l’ordre de tri

Exemple ascendant :

updated_at ASC
order_id ASC

la reprise s’écrit alors :

updated_at > last_updated_at
OR
updated_at = last_updated_at AND order_id > last_order_id

Si le sens du tri change, le sens du prédicat doit changer aussi.


7. N’utilisez pas MAX(updated_at) seul sans penser aux égalités

Exemple d’échec :

ligne A updated_at = 10:00:00
ligne B updated_at = 10:00:00

le pipeline ne traite que A
le checkpoint devient 10:00:00

la requête suivante utilise :
updated_at > 10:00:00

La ligne B est sautée.

Persistez suffisamment d’état pour reprendre de manière déterministe.


8. Fenêtres de lot semi-ouvertes

Autre modèle :

[début, fin)

Requête :

SELECT *
FROM source_orders
WHERE updated_at >= @start_time
  AND updated_at <  @end_time;

Après un succès :

début suivant = fin précédente

Cela fonctionne bien lorsque :

  • le traitement est fondé sur des fenêtres de temps
  • les horodatages de la source sont fiables
  • les arrivées tardives sont traitées séparément

9. Les fenêtres semi-ouvertes ne règlent pas les arrivées tardives

Exemple :

événement survenu à 10:30
arrivé dans la source à 12:15

Si votre lot 10:00–11:00 est déjà terminé, l’enregistrement peut être manqué, sauf si l’horodatage de la source reflète l’heure d’arrivée ou de mise à jour, ou si le pipeline relit volontairement une plage de chevauchement.


10. Fenêtres de chevauchement pour les arrivées tardives

Modèle :

dernière fin réussie = 12:00
la lecture suivante commence à 11:45

Ensuite :

relire les données récentes
→ dédupliquer/upsert

Le chevauchement peut améliorer la résilience face aux mises à jour retardées de la source.

Il exige des écritures idempotentes dans la cible.

Ne choisissez pas une durée de chevauchement arbitraire ; fondez-la sur le retard observé de la source.


11. Exemple de chevauchement glissant

SELECT *
FROM source_orders
WHERE updated_at >= DATEADD(minute, -30, @last_successful_end)
  AND updated_at <  @current_end;

Ceci n’est qu’une illustration.

La durée du chevauchement doit découler du comportement de la source et du SLA métier.


12. Persistez le checkpoint après le succès

Mauvais :

1. calculer le nouveau watermark
2. enregistrer le watermark
3. écrire dans la cible
4. l’écriture dans la cible échoue

L’exécution suivante risque de sauter des données.

Correct :

1. lire une source bornée
2. transformer
3. valider
4. écrire dans la cible
5. réconcilier
6. enregistrer le checkpoint

13. Le checkpoint doit décrire le périmètre terminé

Champs utiles :

pipeline_name
source_name
last_successful_watermark
last_successful_tiebreaker
batch_id
completed_at
row_count
status

Cela facilite l’audit et le rejeu.


14. Conservez l’état du checkpoint de façon durable

Ne stockez pas un état de watermark critique uniquement dans :

variable de notebook
fichier temporaire local
mémoire

Utilisez un stockage durable, par exemple :

  • une table de métadonnées
  • une table de contrôle
  • l’état de l’orchestrateur
  • un stockage de checkpoints durable

15. Utilisez un checkpoint par flux logique

Mauvais :

tous les tenants partagent un même watermark

si les tenants progressent indépendamment.

Mieux :

pipeline + source + tenant
→ checkpoint propre

uniquement lorsqu’une progression séparée est nécessaire.


16. Chargement incrémental par manifeste de fichiers

Pour les sources fondées sur des fichiers, suivez les fichiers traités.

Exemple de métadonnées :

source_file
file_size
checksum
received_at
processed_at
batch_id
status

Traitez ensuite uniquement les fichiers nouveaux ou non traités.


17. Le nom de fichier seul ne prouve pas l’unicité

Une source peut écraser :

orders.csv

avec un nouveau contenu.

Utilisez une identité plus forte lorsqu’elle est disponible :

  • version de la source
  • somme de contrôle (checksum)
  • métadonnées de modification du fichier
  • chemin de livraison immuable
  • ID de manifeste

18. Le partitionnement par chemin de fichier peut simplifier la découverte incrémentale

Exemple :

/landing/orders/2026/10/04/*.parquet

Si la source garantit des dossiers de date immuables, le pipeline peut découvrir les nouvelles partitions.

Suivez tout de même l’état de traitement : l’existence d’un répertoire ne prouve pas à elle seule que l’ingestion a réussi.


19. Modèle CDC

La CDC peut émettre :

INSERT
UPDATE
DELETE

avec des informations d’ordre ou de version.

Événement conceptuel :

{
  "operation": "UPDATE",
  "orderId": "123",
  "commitVersion": 9001,
  "updatedAt": "2026-10-04T14:00:00Z"
}

Persistez la position ou le checkpoint CDC après une application réussie.


20. CDC ne signifie pas automatiquement streaming

Vous pouvez consommer la CDC :

en continu

ou :

toutes les 5 minutes
toutes les heures

Le mécanisme de changement de la source et la cadence de traitement sont des décisions distinctes.


21. Utilisez la séquence, le LSN ou la version natifs de la source lorsqu’ils existent

Un jeton d’ordre natif et fiable de la source est souvent plus sûr que les horodatages applicatifs.

Exemples conceptuels :

LSN
version de commit
numéro de séquence de changement
offset

Respectez la sémantique d’ordre documentée par la source.


22. Ne convertissez pas un checkpoint natif de la source en horodatage moins fiable

Si la source fournit des positions CDC exactes et ordonnées, conservez-les.

Convertir :

LSN → horodatage

peut faire perdre de la précision dans l’ordre.


23. Modèle de comparaison d’instantanés (snapshot diff)

Si la source n’expose que son état complet actuel :

instantané actuel
vs
instantané de confiance précédent

Comparez :

  • les nouvelles lignes
  • les lignes modifiées
  • les lignes manquantes / suppressions

C’est plus coûteux, mais cela peut permettre des mises à jour incrémentales de la cible.


24. Modèle de comparaison par hachage (hash-diff)

Calculez un hachage à partir des colonnes pertinentes pour le métier :

from pyspark.sql import functions as F

snapshot = snapshot.withColumn(
    "row_hash",
    F.sha2(
        F.concat_ws(
            "||",
            F.coalesce(F.col("status"), F.lit("<NULL>")),
            F.coalesce(F.col("amount").cast("string"), F.lit("<NULL>")),
            F.coalesce(F.col("currency"), F.lit("<NULL>")),
        ),
        256,
    )
)

Comparez le hachage par clé métier pour détecter les lignes modifiées.

La canonicalisation compte.


25. Ne hachez que les colonnes pertinentes

N’incluez pas de métadonnées volatiles telles que :

horodatage d’ingestion
ID d’exécution du pipeline
horodatage de chargement

sinon chaque ligne paraîtra modifiée.

Ne hachez que les champs source ou métier qui définissent un changement.


26. Normalisez les valeurs avant le hachage

Instabilité possible :

1
1.0
1.00

ou :

NULL
chaîne vide

peuvent représenter des états métier différents ou identiques selon les règles.

Canonicalisez de manière délibérée.


27. MERGE pour les insertions et les mises à jour

PySpark + Delta :

from delta.tables import DeltaTable

target = DeltaTable.forName(
    spark,
    "silver.orders",
)

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.order_id = s.order_id",
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

Validez d’abord l’unicité de la source.


28. Utilisez des correspondances explicites pour un MERGE maîtrisé

Plus sûr pour les schémas gouvernés :

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.order_id = s.order_id",
    )
    .whenMatchedUpdate(
        set={
            "status": "s.status",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .whenNotMatchedInsert(
        values={
            "order_id": "s.order_id",
            "status": "s.status",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .execute()
)

Cela réduit la propagation accidentelle de colonnes indésirables.


29. Ne mettez à jour que lorsque la source est plus récente

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.order_id = s.order_id",
    )
    .whenMatchedUpdate(
        condition="s.updated_at > t.updated_at",
        set={
            "status": "s.status",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        },
    )
    .whenNotMatchedInsertAll()
    .execute()
)

À utiliser uniquement si updated_at représente de manière fiable la récence côté source.


30. Validez l’unicité de la source du MERGE

duplicates = (
    source
    .groupBy("order_id")
    .count()
    .filter(F.col("count") > 1)
)

if duplicates.limit(1).count() > 0:
    raise ValueError(
        "Incremental source contains duplicate order_id values"
    )

Les versions ambiguës de la source doivent être résolues avant le MERGE.


31. Dédupliquez l’entrée incrémentale de manière déterministe

Exemple :

from pyspark.sql.window import Window

w = (
    Window
    .partitionBy("order_id")
    .orderBy(
        F.col("updated_at").desc(),
        F.col("source_version").desc(),
        F.col("_ingested_at").desc(),
    )
)

latest = (
    source
    .withColumn(
        "_rn",
        F.row_number().over(w),
    )
    .filter(F.col("_rn") == 1)
    .drop("_rn")
)

Utilisez des colonnes d’ordre fiables.


32. Ajout incrémental pour les événements immuables

Si les données ne changent jamais :

(
    events.write
    .format("delta")
    .mode("append")
    .saveAsTable("bronze.events")
)

L’ajout (append) est plus simple que MERGE lorsque la source est réellement immuable et que les doublons sont maîtrisés.


33. L’ajout nécessite quand même une stratégie contre les doublons

Les nouvelles tentatives peuvent renvoyer le même événement.

Utilisez :

event_id stable

ainsi qu’une déduplication ou une idempotence en aval lorsque c’est nécessaire.


34. Les suppressions exigent une conception explicite

Si la source peut supprimer des lignes, une requête de « lignes mises à jour » fondée uniquement sur un horodatage peut ne jamais vous dire ce qui a disparu.

Options :

suppression/tombstone CDC
indicateur de suppression logique
réconciliation par instantané de la source
flux de suppressions distinct

Ne supposez pas que des lignes manquantes signifient des suppressions, sauf si le contrat de la source le dit.


35. Modèle de suppression logique (soft delete)

Source :

is_deleted = 1

Ensuite :

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.order_id = s.order_id",
    )
    .whenMatchedDelete(
        condition="s.is_deleted = true"
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

Ne supprimez que lorsque la source communique explicitement une sémantique de suppression.


36. Évitez la réconciliation des suppressions source/cible sur des extractions partielles

Mauvais :

la source du jour contient 1 000 lignes
la cible contient 1 000 000 lignes

absentes de la source du jour
→ supprimées de la cible

C’est faux, sauf si la source du jour est un instantané complet et faisant autorité.


37. La réconciliation d’instantanés peut détecter les suppressions

Si l’instantané de la source fait autorité :

clés actuelles de la source
vs
clés actuelles de la cible

Les clés présentes uniquement dans la cible peuvent alors être des suppressions.

Validez le périmètre :

tenant
date
système source

avant d’appliquer les suppressions.


38. Écrasement incrémental de partitions

Si les données sont naturellement partitionnées par date et qu’une date fait autorité :

reconstruire la partition 2026-10-04
→ ne remplacer que cette partition

Cela peut être plus simple qu’un MERGE au niveau des lignes.

Utilisez le mécanisme sûr de remplacement de partitions de la plateforme.


39. N’écrasez pas toute la table pour le changement d’une seule partition

Mauvais :

lire toute la table
union de la date de remplacement
écraser toute la table

Cela augmente le coût et le risque.

Utilisez un remplacement ciblé.


40. Les chargements incrémentaux ont besoin d’idempotence

Propriété recherchée :

exécuter deux fois la même entrée
→ même état final de la cible

L’idempotence rend les nouvelles tentatives plus sûres.


41. Les travaux en ajout seul ont besoin d’une protection contre les doublons lors des nouvelles tentatives

Approches possibles :

unicité de event_id
batch_id + clé source
suivi par manifeste
déduplication en Silver

Choisissez en fonction de la sémantique de la source.


42. MERGE n’est pas automatiquement idempotent

Si la source contient des doublons ou des valeurs instables, des MERGE répétés peuvent quand même produire des résultats incorrects.

L’idempotence dépend :

  • de clés stables
  • d’un gagnant déterministe côté source
  • des règles de mise à jour
  • de la sémantique de la cible

43. Gérez avec soin les nouvelles tentatives et le checkpoint

Scénario :

l’écriture dans la cible réussit
l’écriture du checkpoint échoue

L’exécution suivante peut relire les mêmes données.

Votre écriture dans la cible doit tolérer le rejeu.

C’est une autre raison pour laquelle l’idempotence compte.


44. Un état d’esprit proche du commit en deux phases

Un pipeline incrémental robuste se comporte souvent ainsi :

préparer un lot borné
→ écrire de façon idempotente
→ valider/réconcilier
→ valider le checkpoint

Ne traitez pas la mise à jour du checkpoint comme une étape annexe sans lien avec le reste.


45. Persistez les métadonnées des lots

Champs utiles pour une table de contrôle :

batch_id
source_start
source_end
source_row_count
target_row_count
status
started_at
completed_at
checkpoint_before
checkpoint_after
code_version

Cela permet le rejeu et l’audit.


46. Réconciliez les nombres de lignes

Exemple :

lignes source lues
doublons source supprimés
lignes invalides mises en quarantaine
lignes insérées
lignes mises à jour
lignes supprimées
lignes cibles dans le périmètre

Rendez les mouvements explicables.


47. Réconciliez aussi les totaux métier

Pour les données financières :

nombre
sum(amount)
sum(fees)
totaux par devise

par lot, date ou tenant.

Le nombre de lignes seul peut passer à côté de montants dupliqués.


48. N’avancez jamais le checkpoint si des contrôles qualité bloquants échouent

Correct :

lecture de la source
→ transformation
→ échec du quality gate
→ lot marqué en échec
→ checkpoint inchangé

Cela préserve la possibilité de rejouer.


49. Distinguez les contrôles qualité d’avertissement des contrôles bloquants

Exemple :

clé métier manquante
→ bloquant

écart inhabituel du nombre de lignes
→ avertissement

Ne gelez pas chaque pipeline à la moindre anomalie.


50. Modèle pour les données tardives

Mesurez :

source_updated_at
vs
ingestion_time

Si les arrivées tardives sont fréquentes :

  • relisez avec un chevauchement
  • utilisez la CDC native de la source
  • reconsidérez le champ de watermark
  • planifiez une réconciliation

Ne les ignorez pas.


51. Un backfill ne doit pas corrompre le checkpoint en production

Gardez :

checkpoint de production

séparé de :

début/fin du backfill

Un rejeu historique ne doit pas faire reculer le watermark de production.


52. Le backfill doit être explicite

Exemple :

backfill_start = 2026-09-01
backfill_end   = 2026-09-08

Enregistrez le périmètre et la raison.


53. Le backfill peut réutiliser la même logique de transformation

Modèle idéal :

même transformation Silver
limite d’entrée différente

Évitez de maintenir un chemin de code pour les chargements de production et un autre pour la réparation historique, sauf si c’est nécessaire.


54. Protégez-vous du chevauchement des écritures de production et de backfill

S’ils modifient les mêmes clés ou partitions :

  • coordonnez les planifications
  • utilisez un MERGE tenant compte des versions
  • isolez le staging
  • définissez des règles de gagnant

Ne supposez pas que les garanties ACID au niveau de la table suffisent à assurer la justesse métier.


55. Staging avant MERGE

Modèle utile :

extraire la source incrémentale
→ écrire dans une table de staging
→ valider
→ MERGE du staging dans la cible

Avantages :

  • lot rejouable
  • diagnostic plus facile
  • instantané de la source isolé

56. Attribuez un ID de lot aux données de staging

Exemple :

staging.orders_incremental
batch_id = 20261004_1400

Cela facilite les nouvelles tentatives et les investigations.


57. Ne videz pas un staging partagé à la légère

Si plusieurs exécutions peuvent se chevaucher, utilisez :

staging limité au lot

plutôt qu’une zone de staging partagée et modifiable.


58. Les mises à jour de la source peuvent arriver dans le désordre

Exemple :

la version 5 arrive
puis la version 4 arrive plus tard

Si possible, utilisez :

version / séquence de la source

plutôt que l’heure d’arrivée pour choisir le gagnant.


59. L’heure d’ingestion n’indique pas la récence côté source

_ingested_at répond à :

quand la plateforme a vu l’enregistrement

et non à :

quelle version de la source est la plus récente

Ne l’utilisez que comme critère de départage final, lorsque c’est approprié.


60. L’ordre des mises à jour CDC compte

Si la source émet :

LSN 100
LSN 101
LSN 102

appliquez et réconciliez selon l’ordre de la source.

Ne triez pas uniquement sur un horodatage métier si l’ordre CDC fait autorité.


61. Les lectures incrémentales sur l’heure d’événement sont risquées pour les entités modifiables

Si une commande créée hier est mise à jour aujourd’hui, mais que vous filtrez uniquement sur :

created_at > hier

vous manquez la mise à jour.

Utilisez :

updated_at
CDC
version

pour les enregistrements modifiables.


62. Un watermark sur la date de création convient aux entités en ajout seul

Adapté lorsque :

les enregistrements ne changent jamais après leur création

Il peut s’agir par exemple de lignes d’audit ou d’événements immuables.

Tenez tout de même compte d’une visibilité retardée des créations s’il existe une latence de commit ou de réplication côté source.


63. Utilisez l’heure de commit de la source lorsqu’elle est disponible

Les horodatages applicatifs peuvent être :

  • fournis par l’utilisateur
  • antidatés
  • décalés de fuseau horaire

Les métadonnées de commit de la base ou de la source peuvent être plus fiables pour la capture incrémentale, lorsqu’elles sont prises en charge.


64. Le décalage d’horloge peut casser les watermarks sur horodatage

Les systèmes distribués peuvent écrire des horodatages depuis des machines dont les horloges diffèrent.

Si un ordre fiable est important, préférez une séquence ou une version native de la source.


65. Évitez d’utiliser current_timestamp() comme watermark de la source

Cela enregistre l’heure du pipeline, pas nécessairement la limite de la source.

Utilisez une borne dérivée de la source ou une borne explicitement définie.


66. Fixez la borne du lot avant la lecture de la source

Modèle :

fin = limite sûre côté source
lire [début, fin)

Cela évite une fenêtre de requête mouvante pendant l’exécution.


67. Utilisez des bornes décalées lorsque les commits de la source se stabilisent tardivement

Exemple conceptuel :

heure actuelle - délai de stabilisation de la source

peut réduire la lecture de données partiellement validées ou répliquées.

À n’utiliser que si le comportement de la source le justifie.


68. Pagination et chargement incrémental sont deux choses différentes

Pagination :

comment récupérer un jeu de résultats borné en plusieurs morceaux

Chargement incrémental :

quels changements appartiennent à la prochaine exécution du pipeline

Un pipeline peut avoir besoin des deux.


69. Conservez le curseur de pagination jusqu’à la fin de l’extraction bornée

Si une plage incrémentale d’API renvoie plusieurs pages :

fenêtre de watermark
→ page 1
→ page 2
→ page 3

N’avancez pas le watermark durable de la source après la page 1.

Terminez d’abord l’intervalle borné en entier.


70. Exemple d’extraction incrémentale depuis une API

Requête conceptuelle :

GET /orders?
updated_after=2026-10-04T10:00:00Z
&updated_before=2026-10-04T11:00:00Z
&cursor=...

Traitez toutes les pages de la fenêtre.

Puis validez :

watermark = 11:00

71. Les curseurs d’API peuvent expirer

Si un curseur expire au milieu d’une fenêtre, le client a besoin d’une stratégie de redémarrage.

Options :

  • redémarrer la fenêtre bornée de manière idempotente
  • utiliser un jeton de page durable si le fournisseur le permet
  • découper en fenêtres plus petites

Ne prenez pas comme seul checkpoint un curseur éphémère sans comprendre son cycle de vie.


72. Les limites de débit influencent la conception du chargement incrémental

Un arriéré important peut générer de nombreux appels d’API.

Respectez :

  • 429
  • Retry-After
  • les limites de concurrence

Ne transformez pas une exécution de rattrapage en attaque par déni de service.


73. Le chargement incrémental doit pouvoir reprendre

Un lot en échec doit avoir un point de reprise connu.

Demandez-vous :

Quelle plage exacte de la source la nouvelle tentative va-t-elle lire ?
Quel état de la cible existe déjà ?
La même source peut-elle être réappliquée sans risque ?

74. Persistez le périmètre de l’échec

Exemple :

batch_id
watermark de début
watermark de fin
dernière page terminée
statut de l’écriture dans la cible
statut qualité

Cela améliore la maîtrise de la reprise.


75. Ne modifiez pas les checkpoints manuellement à la légère

Modifier :

last_successful_watermark

peut sauter ou dupliquer des données.

Si une réparation manuelle est nécessaire :

  • enregistrez la valeur d’origine
  • définissez le périmètre du rejeu
  • vérifiez l’idempotence de la cible
  • documentez la raison

76. Réparer un checkpoint est un changement de production

Traitez-le comme :

  • une correction de données
  • une migration
  • une étape de runbook opérationnel

et non comme une simple mise à jour de métadonnées.


77. Les chargements incrémentaux ont besoin d’observabilité

Suivez à chaque exécution :

lignes source
lignes insérées
lignes mises à jour
lignes supprimées
lignes en double
lignes invalides
durée
checkpoint avant/après
lignes tardives

Cela aide à détecter une dérive silencieuse.


78. Une absence soudaine de changements peut être suspecte

Causes possibles :

source légitimement inactive
watermark trop en avance
bug de filtre
panne de la source
problème d’authentification/d’API
erreur de fuseau horaire

Tenez compte du contexte avant de conclure au succès.


79. Un volume de changements soudainement énorme peut être suspect

Causes possibles :

réinitialisation du watermark
backfill côté source
pages d’API en double
changement de schéma
bug de la source
position CDC rejouée

Enquêtez avant d’appliquer aveuglément.


80. Monotonie du checkpoint

Pour les sources monotones :

nouveau checkpoint
>=
ancien checkpoint

Un recul doit correspondre à un backfill ou à une reprise volontaire, et non à une modification accidentelle de l’état de production.


81. Alignez le périmètre du checkpoint sur le filtre de la source

Si le checkpoint est défini par tenant :

watermark du tenant A
watermark du tenant B

les lectures et écritures doivent alors respecter ce périmètre.

Ne mettez pas à jour un watermark global à partir de la progression d’un seul tenant.


82. La dérive de schéma peut casser les chargements incrémentaux en silence

Exemple :

updated_at renommé

Le pipeline peut :

  • échouer
  • lire zéro ligne
  • produire des valeurs nulles

Validez les colonnes de watermark requises avant le traitement.


83. Changer de champ de watermark est une migration

Passer de :

updated_at
→ source_version

exige une bascule maîtrisée.

Définissez :

  • l’ancien checkpoint
  • la position de départ du nouveau checkpoint
  • le chevauchement
  • la validation

Ne modifiez pas la logique de production sans analyse du rejeu.


84. Changer la clé du MERGE est dangereux

Si la clé de la cible passe de :

order_id

à :

merchant_id + order_id

les données existantes de la cible et la logique incrémentale doivent migrer de façon cohérente.

Sinon, les mises à jour peuvent toucher les mauvaises lignes ou dupliquer des entités.


85. La logique incrémentale doit être déterministe

Les mêmes :

lot source
+
version du code
+
données/version de référence

doivent produire le même résultat dans la cible, dans la mesure du possible.

Évitez les dépendances cachées à l’heure courante.


86. Modèle incrémental SCD Type 1

Pour les dimensions où la valeur courante est écrasée :

clé métier
→ MERGE des dernières valeurs de la source dans la ligne courante

Aucun historique n’est conservé.

Adapté lorsque l’historique des changements d’attributs n’est pas requis.


87. Modèle incrémental SCD Type 2

Conceptuellement :

attribut modifié
→ faire expirer la ligne courante
→ insérer une nouvelle version

Champs typiques :

effective_from
effective_to
is_current

C’est plus complexe qu’un MERGE classique.

À utiliser lorsque l’état historique est un réel besoin.


88. SCD Type 2 exige de la rigueur sur les doublons et les versions

Si plusieurs changements de la source pour une même clé arrivent dans un même lot, ordonnez-les selon une séquence de changement fiable de la source.

Ne supposez pas qu’il n’y a qu’un changement par clé et par lot.


89. Les chargements de faits par instantané peuvent utiliser le remplacement de partitions

Pour un instantané quotidien qui fait autorité :

snapshot_date = 2026-10-04

remplacez uniquement la partition de ce jour.

Cela peut être plus simple qu’une détection des changements au niveau des lignes.


90. Les chargements de faits d’audit utilisent souvent l’ajout

Pour les événements de transaction ou d’audit immuables :

ajouter les nouvelles lignes

avec des clés d’événement stables et une protection contre les doublons.


91. Séparez le checkpoint d’ingestion du checkpoint de transformation si nécessaire

Exemple :

extraction brute de l’API terminée jusqu’à 11:00
traitement Silver terminé jusqu’à 10:00

Ce sont des étapes différentes.

Un watermark unique peut masquer l’endroit où se trouve l’arriéré.


92. Des checkpoints par couche peuvent améliorer la reprise

Exemple :

position source en Bronze
position traitée en Silver
position publiée en Gold

Utile dans les plateformes à plusieurs étapes.

Ne créez pas de complexité de checkpoint inutile pour des pipelines simples.


93. La progression du checkpoint fait partie de la fraîcheur

Si Bronze est à jour mais que le watermark Gold est en retard, les données présentées aux utilisateurs restent périmées.

Supervisez la progression de bout en bout.


94. Les lectures incrémentales doivent être bornées lorsque c’est possible

Évitez :

updated_at > last_watermark

sans borne supérieure fixe sur un travail de longue durée.

Définissez plutôt :

début
fin

au début de l’exécution, lorsque la sémantique de la source le permet.

Cela facilite le rejeu et la réconciliation.


95. Une extraction bornée permet des nouvelles tentatives reproductibles

Si le lot est :

[10:00, 11:00)

relancez sur le même périmètre.

Ne laissez pas la nouvelle tentative dériver vers :

[10:00, current_time)

sauf si c’est voulu.


96. Une stratégie de reconstruction doit exister

Tôt ou tard, vous pourriez avoir besoin de :

retraiter un jour
retraiter un tenant
reconstruire toute la table Silver

Concevez la logique incrémentale pour que ce soit possible.


97. L’incrémental est une optimisation, pas la source de vérité

La source de vérité doit rester claire :

base de données source
journal brut des événements
couche Bronze
fichiers faisant autorité

Le checkpoint ne fait que suivre la progression.


98. Testez les scénarios d’échec

Testez au minimum :

la source renvoie des doublons
l’écriture dans la cible réussit mais le checkpoint échoue
le checkpoint réussit mais la publication en aval échoue
un enregistrement tardif arrive après le watermark
une suppression apparaît
le schéma change
un backfill chevauche une exécution de production

99. Utilisez une liste de vérification de mise en œuvre reproductible

Avant la production :

1. Définir la source de vérité
2. Choisir un indicateur de changement fiable
3. Définir un ordre déterministe
4. Définir un périmètre de lecture borné
5. Définir la stratégie de doublons/d’idempotence
6. Définir la sémantique des insertions/mises à jour/suppressions
7. Définir la politique de données tardives
8. Définir un checkpoint durable
9. Définir le contrôle qualité/de réconciliation
10. Définir la procédure de nouvelle tentative/de backfill

Si l’un de ces points est inconnu, la conception incrémentale est incomplète.

Interpréter le résultat

Modèle Usage idéal Risque principal
High-water mark sur ID croissant Événements ordonnés immuables L’ordre supposé peut être faux
Watermark sur horodatage Enregistrements modifiables avec heure de mise à jour fiable Égalités, mises à jour tardives, problèmes d’horloge
Horodatage + critère de départage Enregistrements modifiables ordonnés Davantage d’état de checkpoint
Séquence CDC/LSN Bases de données / flux de changements Sémantique propre à chaque source
Manifeste de fichiers Ingestion de fichiers Fichiers remplacés / identité de fichier faible
Comparaison d’instantanés Source exposant l’état actuel complet Comparaison coûteuse
Comparaison par hachage Instantanés larges Erreurs de canonicalisation
Remplacement de partitions Tranches bornées qui font autorité Mauvais périmètre d’écrasement
MERGE/upsert Insertions + mises à jour Clés de source en double / concurrence
Fenêtre de chevauchement Changements tardifs de la source Exige des écritures idempotentes

Le principe fondamental est :

le chargement incrémental est une gestion d’état

et non une simple requête filtrée.

Points à vérifier

Des lignes manquent après un redémarrage

Vérifiez :

  • un checkpoint avancé trop tôt
  • des égalités d’horodatage
  • des lignes arrivées en retard
  • un ordre non déterministe
  • le checkpointing de la pagination

Des lignes en double apparaissent

Vérifiez :

  • un rejeu après l’échec du checkpoint
  • une nouvelle tentative en ajout seul
  • une clé d’événement ou métier manquante
  • des enregistrements en double dans la source
  • des doublons dans la source du MERGE

D’anciennes valeurs écrasent des valeurs plus récentes

Vérifiez :

  • des mises à jour de la source arrivées dans le désordre
  • l’utilisation de l’heure d’ingestion au lieu de la version de la source
  • l’absence de condition « source plus récente que la cible »

Les suppressions n’atteignent jamais la cible

Vérifiez si la source expose :

  • un indicateur de suppression
  • un tombstone (marqueur de suppression)
  • une suppression CDC
  • un instantané qui fait autorité

Un simple watermark de mise à jour peut ne pas capturer les suppressions.

Le travail incrémental relit soudain tout

Vérifiez :

  • un checkpoint réinitialisé ou manquant
  • un filtre de source modifié
  • la conversion de type ou de fuseau horaire de l’horodatage
  • un bogue de migration du watermark

Le travail lit zéro ligne de manière inattendue

Vérifiez :

  • un watermark trop en avance
  • une panne de la source
  • le fuseau horaire du filtre
  • une colonne de watermark manquante ou renommée
  • un mauvais périmètre de tenant ou de source

Notes de production

Les checkpoints sont des données de production

Protégez-les par :

  • la durabilité
  • l’auditabilité
  • des mises à jour maîtrisées
  • des sauvegardes lorsque c’est pertinent

C’est l’idempotence qui rend les nouvelles tentatives sûres

Partez du principe qu’un lot peut être rejoué.

Concevez la cible de sorte que le rejeu ne corrompe pas l’état.

Les horodatages de la source ne sont pas toujours fiables

Préférez un séquencement natif de la source lorsqu’il est disponible.

Les données tardives sont normales dans les systèmes distribués

Définissez sur la base de faits jusqu’où vous devrez peut-être relire ou réconcilier.

Les suppressions exigent une sémantique explicite

N’inférez pas une suppression à partir d’une absence, sauf si la source est un instantané complet qui fait autorité.

Les backfills font partie de l’architecture

La réparation historique ne devrait pas exiger de bricolages ponctuels sur les checkpoints.

Erreurs fréquentes

1. Utiliser MAX(updated_at) comme unique checkpoint

Les égalités d’horodatage peuvent faire sauter des lignes.

2. Avancer le checkpoint avant la réussite de l’écriture

Cela peut faire sauter des données de façon permanente.

3. Supposer que MERGE rend chaque nouvelle tentative sûre

L’unicité de la source et des règles de mise à jour déterministes restent indispensables.

4. Utiliser la date de création pour des enregistrements modifiables

Les mises à jour d’anciennes lignes seront manquées.

5. Ignorer les suppressions

L’état de la cible diverge progressivement de celui de la source.

6. Traiter l’heure d’ingestion comme une version de la source

Des données plus anciennes arrivées en retard peuvent écraser un état plus récent.

7. Modifier manuellement les watermarks sans plan de rejeu

Cela crée des trous ou des doublons silencieux.

8. Laisser les backfills modifier les checkpoints de production

La réparation historique doit être isolée de l’état de progression en production.

9. Utiliser le seul nom de fichier comme identité de traitement

Les sources peuvent écraser ou renvoyer le même nom.

10. Ne pas avoir de périmètre borné pour les nouvelles tentatives

Si une nouvelle tentative lit un intervalle de source différent de celui de l’exécution en échec, la réconciliation devient difficile.

Étape suivante

Utilisez les capacités de la source et le symptôme d’échec pour choisir l’action suivante.

  • Événements ordonnés immuables → utilisez une séquence de la source / un high-water mark.
  • Horodatage de mise à jour fiable → utilisez horodatage + critère de départage déterministe.
  • La source fournit CDC/LSN/version → préférez la position de changement native.
  • Source de fichiers → utilisez un manifeste avec une identité de fichier durable.
  • Instantanés complets uniquement → utilisez une comparaison d’instantanés / de hachages via un staging.
  • Besoin d’insertions et de mises à jour → utilisez un MERGE/upsert déterministe.
  • Besoin des suppressions → ajoutez une sémantique de tombstone/CDC/réconciliation d’instantanés.
  • Des lignes tardives sont manquées → ajoutez un chevauchement ou passez à une séquence de source plus fiable.
  • Les nouvelles tentatives créent des doublons → renforcez l’idempotence et la gestion des clés.
  • Un backfill est nécessaire → utilisez un périmètre historique explicite sans modifier le checkpoint de production.
  • La logique incrémentale devient trop complexe → réévaluez si une reconstruction bornée complète ou par partition serait plus simple et plus sûre.

← Tous les aide-mémoire