Split Out et Aggregate dans n8n : transformer un tableau en items, et inversement

Le premier mur sur lequel butent la plupart des débutants n8n n'est ni une expression JavaScript ni un credential mal configuré : c'est le modèle de données. Dans n8n, tout ce qui circule entre deux nodes est une liste d'items, et chaque node s'exécute une fois par item reçu. Tant qu'on n'a pas intégré cette règle, on ne comprend pas pourquoi un node d'envoi d'email tourne cinquante fois, ni pourquoi une réponse d'API qui contient visiblement cinquante résultats n'en affiche qu'un seul dans l'interface. Les nodes Split Out et Aggregate sont les deux leviers natifs pour piloter cette mécanique : le premier éclate un tableau en N items individuels, le second regroupe N items en un seul. Maîtriser cet aller-retour, c'est débloquer 80 % des situations de restructuration de données dans n8n.

Le modèle de données de n8n en trente secondes

Entre deux nodes, les données transitent toujours sous la même forme : une liste d'objets JSON, appelés items. Un node qui reçoit 50 items s'exécute 50 fois (une fois par item), et un node qui en reçoit un seul ne s'exécute qu'une fois. Cette convention rend les workflows prévisibles, mais elle crée deux situations inconfortables :

• Le tableau caché dans un item. Une API renvoie souvent sa liste de résultats à l'intérieur d'un seul objet JSON : {"results": [...50 objets...]}. Pour n8n, c'est un seul item contenant un champ tableau — les nodes suivants ne s'exécuteront donc qu'une fois, sur le paquet entier, alors que vous vouliez traiter chaque résultat individuellement.
• Les items qu'on voudrait fusionner. À l'inverse, après avoir traité 50 items, vous voulez parfois produire une seule sortie : un email récapitulatif, un résumé généré par un LLM, un fichier d'export. Sans regroupement, le node final s'exécuterait 50 fois et vous enverriez 50 emails.

Split Out règle le premier cas, Aggregate le second. Cette idée de restructurer des données par transformations successives — plier, déplier, découper — n'a d'ailleurs rien de nouveau : le système Potter's Wheel présenté par Raman et Hellerstein à la conférence VLDB en 2001 (Potter's Wheel: An Interactive Data Cleaning System — voir sur Google Scholar) formalisait déjà des opérations de fold, unfold et split appliquées interactivement à des données tabulaires. Split Out et Aggregate en sont les héritiers directs, appliqués au JSON qui circule dans vos workflows.

Split Out : éclater un champ tableau en N items

Le node Split Out prend un item contenant un champ de type tableau et produit un item de sortie par élément de ce tableau. Sa configuration tient en deux paramètres :

• Fields To Split Out : le nom du champ tableau à déplier — par exemple results, ou un chemin imbriqué comme data.items.
• Include : ce qu'il faut faire des autres champs de l'item d'origine — ne rien conserver, conserver tous les autres champs (répliqués sur chaque item de sortie), ou seulement une sélection.

Exemple typique : un node HTTP Request interroge une API de CRM qui répond {"total": 3, "contacts": [{"nom": "Martin"}, {"nom": "Durand"}, {"nom": "Leroy"}]}. En sortie, n8n affiche 1 item. Un Split Out configuré sur le champ contacts transforme cette sortie en 3 items, un par contact — et chaque node suivant (enrichissement, envoi, écriture en base) s'exécutera bien trois fois, une fois par contact. Si l'API pagine ses résultats, ce dépliage se combine naturellement avec la pagination des appels HTTP Request : chaque page rapporte son tableau, que Split Out remet à plat.

À noter : si le champ dépliant contient des objets, chaque item de sortie reçoit directement les clés de l'objet. S'il contient des valeurs simples (une liste de chaînes, par exemple), chaque valeur est placée dans un champ dont vous contrôlez le nom.

Aggregate : regrouper N items en un seul

Le node Aggregate fait le chemin inverse, avec deux modes de fonctionnement dans son paramètre Aggregate :

• Individual Fields : vous désignez un ou plusieurs champs à collecter ; chaque champ devient un tableau rassemblant les valeurs de tous les items entrants. 50 items avec un champ email deviennent 1 item avec un champ email contenant 50 adresses. Pratique pour construire une liste de destinataires ou un tableau de valeurs à passer en paramètre.
• All Item Data : chaque item entier est placé, avec tous ses champs, dans un tableau sous une clé unique (data par défaut). C'est le mode « je garde tout » : 50 items deviennent 1 item contenant un tableau de 50 objets complets.

Le résultat, dans les deux cas, est un seul item en sortie — et donc une seule exécution pour tout ce qui suit.

Trois cas d'usage concrets

Déplier une réponse d'API. C'est le cas Split Out par excellence, décrit plus haut : une API renvoie un tableau encapsulé dans un objet, et vous voulez traiter chaque élément individuellement. Sans Split Out, les débutants se retrouvent à écrire des expressions du type {{ $json.results[0].name }} en dur, qui ne traitent que le premier élément et ignorent silencieusement les autres.

Préparer un résumé unique pour un LLM. Vous avez 30 items (des tickets support, des avis clients, des lignes de veille), et vous voulez que le modèle produise une seule synthèse de l'ensemble. Un Aggregate en mode « All Item Data » juste avant le node IA fusionne tout en un item : le prompt peut alors référencer {{ JSON.stringify($json.data) }} et le LLM ne reçoit qu'un appel, avec tout le contexte. Sans l'Aggregate, le node IA tournerait 30 fois et produirait 30 résumés d'un seul ticket chacun — en payant 30 appels.

Construire le corps d'un email récapitulatif. Même logique : après avoir extrait 20 lignes d'un fichier (voir notre guide sur l'extraction et la génération de fichiers Excel/CSV), un Aggregate les regroupe, puis un node Code ou une expression construit un tableau HTML ou une liste à puces à partir du tableau agrégé, injecté dans un unique email envoyé une seule fois.

Ne pas confondre avec Loop Over Items ni avec Merge

Trois nodes qui manipulent des listes, trois rôles distincts :

• Split Out change la structure : 1 item contenant un tableau de N éléments → N items. Aucune notion de rythme ou de lot.
• Loop Over Items change le rythme : N items → les mêmes N items, mais traités par lots (batches) de taille choisie, avec une boucle de retour. C'est un outil de cadencement, pas de restructuration — notre guide des boucles n8n détaille quand il est réellement nécessaire, sachant que la plupart des nodes itèrent déjà d'eux-mêmes sur chaque item.
• Merge combine plusieurs branches : il attend les données de deux entrées distinctes du workflow et les rapproche (par position, par clé, ou en les ajoutant bout à bout). Aggregate, lui, travaille sur une seule branche et fusionne les items entre eux — voir notre article sur la combinaison de données avec le node Merge pour les jointures entre sources.

Le trio se combine très bien : Split Out pour déplier la réponse d'une API, Loop Over Items pour traiter les items par lots de 10 en respectant un rate limit, puis Aggregate pour reconstituer un rapport unique en fin de course.

L'alternative en node Code

Quand la restructuration se double d'une logique métier (filtrage conditionnel, renommage, calculs), un node Code peut remplacer les deux nodes d'un coup :

• Équivalent de Split Out : retourner un tableau d'objets. Un return items.flatMap(...) ou plus simplement un return monTableau.map(x => ({ json: x })) produit N items en sortie — n8n interprète chaque élément du tableau retourné comme un item distinct.
• Équivalent d'Aggregate : $input.all() donne accès à la totalité des items entrants dans une même exécution du node (en mode « Run Once for All Items »). Retourner [{ json: { data: $input.all().map(i => i.json) } }] reproduit exactement un Aggregate « All Item Data ».

Notre guide des expressions JavaScript et du node Code couvre ces patterns en détail. La règle de bon sens : pour un simple dépliage ou regroupement, préférez les nodes dédiés — leur configuration est lisible d'un coup d'œil par n'importe qui ouvre le workflow. Réservez le Code aux cas où la transformation est réellement composite.

Pièges fréquents

• Traiter seulement le premier élément sans s'en rendre compte. Une expression {{ $json.results[0].email }} sur un item contenant un tableau fonctionne… pour le premier résultat uniquement. Si le node suivant ne tourne qu'une fois alors que l'API a renvoyé 50 résultats, il manque probablement un Split Out.
• Oublier l'Aggregate avant un node « final ». Envoi d'email, génération de fichier, appel LLM de synthèse : si ce node reçoit N items, il s'exécute N fois. Cinquante emails au lieu d'un seul, ou trente appels IA facturés au lieu d'un — le symptôme classique d'un Aggregate manquant.
• Se tromper de champ dans Split Out. Si le tableau est imbriqué (data.results plutôt que results), pointer le mauvais niveau produit une erreur ou une sortie vide. Vérifiez le chemin exact dans la vue de sortie du node précédent avant de configurer le Split Out.
• Utiliser Merge à la place d'Aggregate. Merge rapproche deux branches distinctes ; il ne fusionne pas N items d'une même branche en un seul. Pour passer de N à 1 sur un flux linéaire, c'est Aggregate qu'il faut.
• Agréger des volumes énormes sans y penser. Un Aggregate « All Item Data » sur des milliers d'items volumineux construit un unique item très lourd, entièrement chargé en mémoire — et souvent trop gros pour la fenêtre de contexte d'un LLM. Sur de gros corpus documentaires, un découpage en chunks adapté au RAG est une bien meilleure stratégie qu'une agrégation brute.

Pour aller plus loin

Split Out et Aggregate sont si centraux qu'on les retrouve dans presque tous les workflows sérieux de traitement de données — à commencer par ceux du Pack Assistant RAG (119 €), dont les workflows d'ingestion documentaire enchaînent précisément ces deux nodes : Split Out pour déplier les listes de documents et de chunks, Aggregate pour reconstituer les contextes avant indexation. Si vous débutez avec le modèle de données de n8n, complétez cette lecture par notre guide des expressions JavaScript pour manipuler finement le contenu des items, et par celui du node Merge pour croiser des données venues de plusieurs sources.