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