Node Aggregate n8n : regrouper tous vos items en un seul (guide complet)

Dans n8n, tout circule sous forme de liste d'items, et chaque node s'exécute une fois par item reçu. La logique est saine jusqu'au moment où le workflow doit produire une seule sortie : un rapport, un appel LLM unique sur cinquante lignes, un fichier CSV, un message Slack récapitulatif. Sans regroupement, vous envoyez cinquante messages et payez cinquante appels. Le node Aggregate (n8n-nodes-base.aggregate) est la réponse native à ce besoin : il fusionne N items en un seul, dont un champ contient un tableau. Ce guide détaille ses deux modes, ses options réelles, la forme exacte de sa sortie, et les erreurs qu'il provoque quand on l'utilise sans comprendre ce qu'il fait au chaînage des données.

Le problème que résout Aggregate

Un node HTTP Request qui pagine, un Split Out qui déplie un tableau, une lecture de base : tous produisent N items. Or certains nodes n'ont de sens qu'appelés une fois — envoyer un digest, écrire un fichier, demander à un modèle de synthétiser un corpus entier.

Cette tension n'a rien de propre à n8n. En traitement de flux, on parle d'opérateur bloquant : un opérateur qui ne peut produire aucune sortie tant qu'il n'a pas consommé la totalité de son entrée. Brian Babcock, Shivnath Babu, Mayur Datar, Rajeev Motwani et Jennifer Widom en font l'un des points durs de leur article de référence « Models and Issues in Data Stream Systems », publié en 2002 aux actes du symposium PODS de l'ACM (voir sur Google Scholar) : les agrégations et les tris bloquent le pipeline, et un opérateur bloquant placé à la racine de l'arbre de requête se comporte très différemment d'un opérateur intercalé au milieu. Le node Aggregate est exactement cela, et la plupart de ses pièges en découlent.

Mode 1 : Individual Fields

Le paramètre principal du node s'appelle Aggregate et propose deux valeurs. La première, Individual Fields, agrège champ par champ.

Pour chaque champ à collecter, vous renseignez :

• Input Field Name : le nom du champ à agréger dans les données entrantes (email, montant, client.nom en dot notation) ;
• Rename Field : un interrupteur qui, une fois activé, fait apparaître Output Field Name pour choisir le nom de la clé en sortie.

Le bouton d'ajout permet d'empiler plusieurs champs : chacun devient un tableau indépendant dans l'item de sortie.

Trois options méritent d'être connues :

• Disable Dot Notation : désactive l'interprétation de parent.enfant comme un chemin. À activer si un nom de champ contient littéralement un point ;
• Merge Lists : quand le champ agrégé contient déjà des tableaux, cette option produit une seule liste à plat au lieu d'une liste de listes. C'est la différence entre [["a","b"],["c"]] et ["a","b","c"] ;
• Keep Missing And Null Values : par défaut, un item dépourvu du champ ne contribue rien au tableau. Activée, elle ajoute une entrée nulle à la place, ce qui préserve l'alignement des indices entre plusieurs champs agrégés.

Une option Include Binaries existe également : elle contrôle l'inclusion des données binaires, non embarquées par défaut.

Mode 2 : All Item Data (Into a Single List)

Le second mode ne trie rien : il prend chaque item entier et l'empile dans un tableau unique.

• Put Output in Field : le nom du champ qui recevra le tableau. La valeur par défaut est data ;
• Include : trois choix — All Fields (tout garder), Specified Fields (qui fait apparaître Fields To Include, une liste de champs séparés par des virgules) et All Fields Except (qui fait apparaître Fields To Exclude, même format).

Ce mode est le réflexe quand vous voulez tout conserver. Include avec All Fields Except est très utile juste avant un appel LLM : on exclut les champs techniques (identifiants internes, timestamps de synchronisation, blobs) pour ne pas gaspiller la fenêtre de contexte.

La forme exacte de la sortie

C'est le point qui déroute le plus, alors autant l'écrire noir sur blanc : Aggregate produit toujours exactement un item. Seule la structure interne change.

En mode All Item Data avec Put Output in Field laissé à data, trois items entrants donnent :

{
  "data": [
    { "email": "a@exemple.fr", "montant": 120 },
    { "email": "b@exemple.fr", "montant": 340 },
    { "email": "c@exemple.fr", "montant": 90 }
  ]
}

En mode Individual Fields avec deux champs déclarés, email et montant, les mêmes données donnent :

{
  "email": ["a@exemple.fr", "b@exemple.fr", "c@exemple.fr"],
  "montant": [120, 340, 90]
}

Les tableaux respectent l'ordre des items entrants — d'où l'intérêt de placer un node Sort juste avant quand l'ordre du rapport final compte. Et dans les deux cas, l'accès en aval se fait par index : {{ $json.data[0].email }} ou {{ $json.email[0] }}. Pour compter les éléments, {{ $json.data.length }}.

Split Out et Aggregate : l'aller-retour

Aggregate est la moitié d'un couple. Split Out déplie un champ tableau en N items, Aggregate recompose N items en un item contenant un tableau. Le pattern classique enchaîne Split Out → traitement item par item → Aggregate, et notre guide sur Split Out et Aggregate détaille ce modèle de données de bout en bout.

Attention toutefois : l'aller-retour n'est pas symétrique. Split Out peut propager les champs de l'item parent sur chaque enfant, mais Aggregate ne les reconstitue pas. Si vous aviez un commande_id au niveau parent et 12 lignes dépliées, l'agrégation rendra 12 lignes — pas la structure d'origine. Reconstruire l'enveloppe demande un node Edit Fields (Set) ou un node Code après coup.

Aggregate, Summarize ou Merge ?

Trois nodes qu'on confond régulièrement :

• Aggregate collecte sans transformer. Les valeurs arrivent telles quelles dans des tableaux, rien n'est calculé, rien n'est perdu ;
• Summarize calcule. Il applique des agrégations statistiques (somme, moyenne, comptage, min, max, concaténation) et sait grouper par champ, comme un GROUP BY SQL. Notre guide du node Summarize couvre ce terrain ; la règle : « chiffre d'affaires par commercial » c'est Summarize, « les 200 lignes brutes dans un item » c'est Aggregate ;
• Merge joint deux entrées distinctes du workflow, par position, par clé ou en concaténation. Il travaille entre branches, là où Aggregate travaille dans une seule branche — voir notre article sur le node Merge.

Aggregate n'est pas un « single batch »

La requête « aggregate items into single batch » cache un malentendu tenace : regrouper des items en un seul item n'a rien à voir avec le traitement par lots. Le node Loop Over Items découpe N items en paquets de taille choisie et les fait défiler dans une boucle : le but est le rythme, typiquement respecter un rate limit d'API. Aggregate ne cadence rien, il change la forme des données pour qu'un node ne s'exécute qu'une fois.

Le gain d'une agrégation avant un appel réseau est pourtant réel, et documenté de longue date. Phillip Bogle et Barbara Liskov l'ont mesuré dans « Reducing Cross Domain Call Overhead Using Batched Futures », présenté à la conférence OOPSLA en 1994 (voir sur Google Scholar) : les franchissements de domaine coûtent souvent bien plus cher que le travail réellement effectué par l'appel, et regrouper des appels potentiellement interdépendants en une seule requête réduit substantiellement ce coût. Trente ans plus tard, le raisonnement s'applique tel quel à un node Aggregate placé devant une API facturée à l'appel.

Quatre cas d'usage concrets

• Un seul prompt LLM sur 50 lignes. All Item Data, puis un prompt qui référence {{ JSON.stringify($json.data) }}. Un appel au lieu de cinquante, et un modèle qui voit l'ensemble et peut comparer — c'est le socle des workflows de synthèse de documents longs ;
• Le corps JSON d'un appel HTTP en bulk. Beaucoup d'API exposent un endpoint /bulk ou /batch qui accepte un tableau d'objets. Un Aggregate All Item Data construit précisément ce tableau, injecté dans le body du node HTTP Request ;
• Un CSV ou un rapport unique. Le node Convert to File attend le lot complet ; un Aggregate en amont garantit un seul fichier plutôt qu'un fichier par ligne, comme détaillé dans notre guide sur les fichiers Excel et CSV ;
• Un digest Slack quotidien. Individual Fields sur titre et url, puis une expression qui construit une liste à puces à partir des deux tableaux. Un message par jour, pas un message par article.

Les pièges classiques

• La perte du chaînage $('Node').item. C'est le piège numéro un. L'item produit descend de N items simultanément : n8n ne peut plus établir la correspondance un pour un, et $('HTTP Request').item.json.id échoue. Notre article sur l'erreur paired item explique le mécanisme ; la parade est d'embarquer les champs nécessaires dans l'agrégation, avant le node Aggregate ;
• L'explosion mémoire. Un item unique contenant 100 000 lignes est intégralement chargé en mémoire, et il l'est aussi dans les données d'exécution sauvegardées. Agrégez après avoir filtré et limité, jamais avant ;
• Les valeurs nulles silencieuses. En mode Individual Fields, un item sans le champ ne produit aucune entrée : deux champs agrégés peuvent finir avec des tableaux de longueurs différentes, et vos indices se décalent. Keep Missing And Null Values règle ce cas précis ;
• Agréger à l'intérieur d'une boucle. Un Aggregate placé sur la branche « loop » d'un Loop Over Items n'agrège que le batch courant. Pour un résultat global, il doit se trouver sur la sortie « done », après la boucle ;
• Les données binaires laissées de côté. Les pièces jointes ne suivent pas par défaut ; l'option Include Binaries existe, mais agréger des binaires reste coûteux — lisez notre guide sur la gestion des fichiers volumineux avant de s'y risquer ;
• Confondre 1 item et 1 valeur. Après Aggregate, $json.email est un tableau, pas une chaîne. Une expression écrite comme avant l'agrégation produira a@x.fr,b@x.fr,c@x.fr par coercition implicite — inaperçu jusqu'au jour où un destinataire reçoit une adresse concaténée.

En résumé

Aggregate transforme N items en un seul, point. Deux modes : Individual Fields pour collecter des champs choisis dans des tableaux nommés, All Item Data (Into a Single List) pour empiler les items complets sous la clé définie par Put Output in Field. Les options qui comptent vraiment sont Merge Lists (aplatir des tableaux de tableaux) et Keep Missing And Null Values (préserver l'alignement des indices). Retenez enfin les deux conséquences : la sortie s'adresse toujours par index, et le chaînage $('Node').item ne survit pas à l'opération.

Pour aller plus loin

Le pattern « agréger avant l'appel au modèle » est au cœur des workflows du Pack Assistant RAG (119 €), où les extraits récupérés dans la base vectorielle sont regroupés en un contexte unique avant d'atteindre le LLM. Côté traitement d'emails, le Pack Inbox IA (79 €) applique la même mécanique pour produire un digest quotidien : un seul message de synthèse plutôt qu'une notification par email traité.