Introduction

Dans les workflows n8n réels, vous avez rarement une seule ligne d'exécution linéaire. Plus souvent, vous séparez le flux : une branche interroge votre CRM, une autre récupère les analytics, une troisième attend un webhook d'un client. À un moment donné, vous devez rassembler ces branches parallèles — et c'est précisément à cela que sert le nœud Merge. Comprendre comment combiner correctement les branches évite les pertes de données, le traitement en double et les bugs silencieux qui n'apparaissent qu'en production.

Cette leçon couvre les trois principales stratégies de fusion dans n8n : attendre toutes les entrées, fusionner par une clé correspondante (jointure style SQL) et ajouter (concaténer) tous les items entrants. Chaque strategy a une finalité différente, et choisir la mauvaise est l'une des erreurs les plus fréquentes lors de la construction d'automatisations non triviales.

Comment fonctionne le nœud Merge

Le nœud Merge prend plusieurs flux d'entrée (Input 1, Input 2, éventuellement plus) et produit un seul flux de sortie. Il ne s'exécute que lorsque chaque entrée connectée a fourni au moins un item, ce qui signifie qu'il synchronise implicitement les branches. C'est le comportement « wait » : quelle que soit la rapidité d'une branche, le nœud Merge attend jusqu'à ce que la branche la plus lente arrive.

Vous pouvez également ajouter un délai d'attente dans les paramètres du nœud. Si une branche ne se termine jamais, la fusion finira par cesser d'attendre et supprimera les données ou continuera avec ce qui est arrivé. Cela importe pour les workflows de longue durée où une API externe pourrait rester bloquée.

Fusion par clé (comportement de jointure)

C'est l'équivalent le plus proche d'un JOIN SQL. Vous choisissez un champ (par exemple `email` ou `orderId`) qui existe dans les deux flux d'entrée, et le nœud apparie les items qui partagent la même valeur. Les items sans correspondance sont supprimés par défaut, mais vous pouvez configurer le mode pour qu'il se comporte comme un LEFT JOIN (conserver les items non appariés de l'Input 1) ou comme une jointure externe.

Le résultat est un item par correspondance, avec les champs des deux entrées combinés. Les options du menu déroulant sont :

Append : concatène tous les items des deux entrées dans une liste plate, dans l'ordre, sans appariement. Utilisez cette option lorsque les branches produisent des enregistrements indépendants qui doivent simplement être traités ensemble plus tard (par exemple, tous les contacts de Mailchimp et tous les contacts de HubSpot mis en file d'attente pour une seule étape de déduplication).

Merge By Key : apparie les items sur un champ partagé, comme une jointure de base de données. Utilisez cette option lorsque chaque item d'un côté correspond logiquement à un item de l'autre côté, comme faire correspondre un enregistrement de commande avec son enregistrement de paiement correspondant.

Wait : le mode le plus simple — il n'effectue aucune transformation, il synchronise seulement le timing. Les items de sortie suivent l'ordre de l'Input 1, et les items de l'Input 2 sont simplement attachés un-à-un par position. Utilisez cette option uniquement lorsque vous contrôlez les deux branches et savez que l'ordre correspond.

Le menu déroulant Mode propose ces quatre options : Append, Merge By Key, Merge By Position et Wait. Notez que « Merge By Position » est le nom technique du comportement simple d'attente et d'appariement — il apparie les items par leur index dans le tableau d'entrée, ce qui ne fonctionne correctement que lorsque les deux branches ont le même nombre d'items dans le même ordre.

Exemple pratique : combiner les données de commandes et de paiements

Imaginez que la Branche 1 récupère les commandes depuis une base de données, et que la Branche 2 récupère le statut de paiement depuis Stripe. Chaque branche produit des items avec un champ `orderId`. Vous voulez un enregistrement combiné par commande.

{
  "node": "Merge",
  "type": "n8n-nodes-base.merge",
  "parameters": {
    "mode": "mergeByKey",
    "joinMode": "inner",
    "propertyName1": "orderId",
    "propertyName2": "orderId"
  }
}

Avec `joinMode` réglé sur `inner`, seules les commandes qui existent dans les deux branches se retrouvent dans la sortie. Si vous passez sur `left`, les commandes qui n'ont pas encore d'enregistrement de paiement continuent tout de même en aval, marquées comme non appariées — utile pour repérer les paiements manquants.

Erreurs courantes et pièges

L'erreur la plus fréquente est d'utiliser « Merge By Position » lorsque les deux branches produisent un nombre différent d'items. Si la Branche 1 renvoie 10 commandes et la Branche 2 seulement 7 enregistrements de paiement, 3 des items de commande seront soit appariés avec des données de paiement `null`, soit silencieusement supprimés selon les paramètres. Utilisez toujours « Merge By Key » lorsque les nombres peuvent différer.

Un autre piège : le nœud Merge ne déduplique pas. Si la Branche 1 contient deux fois le même email et la Branche 2 une seule fois, vous pouvez obtenir des lignes jointes en double. La déduplication doit se faire avant la fusion, ou avec un nœud séparé après.

Enfin, rappelez-vous que Merge attend chaque entrée connectée. Si vous oubliez de connecter une entrée, le nœud attendra indéfiniment (ou jusqu'au délai d'attente). Les entrées non connectées sont une cause fréquente de workflows qui se bloquent en production.

Résumé

Le nœud Merge est le point de synchronisation de tout workflow multi-branches. Utilisez Append lorsque vous voulez simplement empiler des listes indépendantes, Merge By Key lorsque les items de chaque côté sont liés par un identifiant partagé, et Wait / Merge By Position uniquement lorsque les deux branches produisent des tableaux appariés de même longueur. Vérifiez toujours que chaque entrée est connectée, choisissez un mode de jointure qui correspond à vos besoins d'intégrité des données, et placez la déduplication en dehors de la fusion pour éviter les surprises.