Introduction

Lorsqu'un workflow n8n reçoit une liste d'éléments — par exemple 500 lignes d'un tableur ou 1 000 contacts provenant d'une API — envoyer naïvement chacun d'eux au nœud suivant peut poser problème : limites de débit, timeouts, pics de mémoire ou verrouillage de tables en base de données. Le nœud SplitInBatches résout ce problème en découpant une liste en petits groupes et en les libérant un lot à la fois, ce qui laisse aux nœuds en aval le temps de souffler entre chaque groupe.

Imaginez un tapis roulant maîtrisé : au lieu de déverser 1 000 cartons d'un coup sur un opérateur, vous les faites arriver 50 par 50.

Comment fonctionne SplitInBatches

SplitInBatches se place entre votre source de données et le nœud qui traite chaque élément. Lors de la première exécution, il émet le premier lot (taille configurable, 1 élément par défaut), fait une pause, puis lors des exécutions suivantes émet le lot suivant jusqu'à épuisement de la liste. Chaque lot passe par la même branche en aval, c'est pourquoi on l'associe généralement à un nœud Set, HTTP Request ou de base de données.

Le nœud dispose de deux sorties importantes : « Done » se déclenche une seule fois après la libération du dernier lot — utile pour une étape finale de résumé ou de nettoyage — et « Loop » renvoie le lot suivant dans votre branche de traitement.

Configuration de base

Ouvrez le nœud et réglez Batch Size sur un nombre correspondant à ce que votre service en aval peut gérer. Pour la plupart des API HTTP limitées à 100 requêtes par minute, un Batch Size de 10 avec un nœud Wait de 6 secondes entre les lots fonctionne bien.

{
  "node": "SplitInBatches",
  "parameters": {
    "batchSize": 10,
    "options": {}
  },
  "type": "n8n-nodes-base.splitInBatches"
}

Reliez la sortie « Loop » à votre nœud de traitement, puis depuis ce nœud, rebranchez vers SplitInBatches pour que le lot suivant puisse être libéré. Reliez la sortie « Done » à l'étape de résumé dont vous avez besoin.

Exemple pratique : envoyer des contacts vers une API externe

Imaginez que vous avez récupéré 200 contacts depuis un CRM et que vous devez faire un POST pour chacun vers un webhook. Sans batching, vous déclencheriez 200 requêtes instantanément et vous heurteriez probablement à une erreur 429 Too Many Requests.

Le workflow ressemble à ceci : un déclencheur Cron s'exécute quotidiennement, un nœud HTTP Request récupère les contacts, SplitInBatches les regroupe par 10, chaque lot entre dans une boucle qui appelle le webhook pour chaque élément, puis un nœud Wait fait une pause de 6 secondes, puis le contrôle revient à SplitInBatches pour le lot suivant. Une fois tous les lots traités, la branche « Done » envoie « Synced 200 contacts » dans Slack.

Erreurs courantes

Oublier de rebrancher la boucle est l'erreur numéro un — sans cette connexion, le workflow s'arrête après le premier lot. Une autre erreur fréquente consiste à placer le nœud Wait après SplitInBatches au lieu de l'intérieur de la branche de boucle ; cela annule son utilité car aucun throttling ne se produit entre les lots. Enfin, gardez à l'esprit que SplitInBatches conserve son état par exécution, donc chaque nouvelle exécution du déclencheur repart du lot 1 — vous ne pouvez pas reprendre une boucle de lots à moitié terminée d'une exécution à l'autre.

Résumé

SplitInBatches est le nœud de référence dès qu'un service en aval ne peut pas absorber votre liste complète en une seule fois. Définissez un Batch Size raisonnable en fonction de la limite de débit de l'API cible, rebranchez toujours la sortie Loop, associez-le à un nœud Wait à l'intérieur de la boucle pour un rythme respectueux des limites, et utilisez la branche « Done » pour les tâches de fin d'exécution.

Pour des listes de plus de quelques centaines d'éléments ou pour du traitement parallèle, tournez-vous vers le nœud Loop ou un sous-workflow avec un déclencheur Execute Workflow — ces sujets sont abordés dans des leçons ultérieures.