Les données dans n8n

4.1Une liste d'éléments

Tout ce qui passe d'un nœud à un autre a la même forme : une liste d'éléments (items). Un élément représente une chose : une demande de devis, un produit, un e-mail, une ligne de tableur. Un nœud reçoit une liste, fait son travail, et rend une liste à son tour.

Le workflow Ch04 · Éléments le montre. Il lit les produits de la table, calcule un prix soldé de 10 %, regroupe tout, puis sépare de nouveau.

Le déclencheur manuel produit un élément vide : il ne fait que donner le départ. Le nœud Lire les produits en rend six, un par ligne de la table. Prix soldé en reçoit six et en rend six. Regrouper les fond en un seul, Séparer les éclate de nouveau en six.

4.2Un nœud, une exécution par élément

Prix soldé est un nœud Edit Fields qui ajoute un champ prix_solde, de type nombre, avec pour valeur l'expression :

{{ $json.prix * 0.9 }}

On n'a écrit cette expression qu'une fois, et pourtant chaque produit a reçu son propre prix soldé : 1 350 francs pour le savon à 1 500, 1 980 pour l'huile à 2 200. C'est la règle de n8n : un nœud traite chaque élément qu'il reçoit. L'expression est évaluée pour chacun, et $json désigne à chaque fois l'élément en cours de traitement.

La règle vaut pour tous les nœuds qui agissent. Un nœud d'envoi d'e-mail qui reçoit cinquante éléments envoie cinquante messages ; un nœud qui crée une fiche dans un CRM en crée autant que d'éléments reçus. C'est commode quand on le veut, et cuisant quand on l'a oublié.

Quelques nœuds échappent à la règle parce que leur travail porte sur la liste entière : ceux qui regroupent, trient, dédoublonnent, comparent ou fusionnent. On les rencontrera au chapitre 5. Le nœud Code, lui, laisse le choix (chapitre 8).

4.3Regrouper et séparer

Le nœud Aggregate (« Regrouper ») fait d'une liste d'éléments un seul élément. Réglé sur All Item Data (Into a Single List), il range tous les éléments reçus dans un tableau, sous le nom choisi dans Put Output in Field : ici, produits.

L'autre mode, Individual Fields, ne garde que certains champs : la liste des noms, la liste des prix. C'est utile pour préparer un message qui récapitule une liste, ou pour transmettre un lot entier à une API qui l'attend en un seul appel.

Le nœud Split Out (« Séparer ») fait l'inverse. Il prend un champ qui contient un tableau, ici produits, et fait un élément de chacune de ses cases. On s'en sert constamment avec les API, qui répondent souvent par un seul objet contenant une liste : une liste de commandes, de contacts, de fichiers. Tant qu'elle reste enfermée dans un élément, les nœuds suivants ne la traiteront qu'une fois ; une fois séparée, ils traiteront chaque commande.

4.4L'anatomie d'un élément

Dans le panneau d'un nœud, la vue JSON montre le contenu des éléments. Mais n8n en conserve un peu plus. Voici le premier élément qui sort de Prix soldé, tel que n8n l'a enregistré dans les données de l'exécution :

[
  {
    "json": {
      "reference": "SAV-001",
      "nom": "Savon de karité 250 g",
      "categorie": "Hygiène",
      "prix": 1500,
      "stock": 120,
      "id": 1,
      "createdAt": "2026-10-05T09:01:06.238Z",
      "updatedAt": "2026-10-05T09:01:06.238Z",
      "prix_solde": 1350
    },
    "pairedItem": {
      "item": 0
    }
  }
]

Un élément est un objet qui peut avoir trois clés.

json contient les données proprement dites. C'est ce que montrent les vues Schema, Table et JSON, et ce que désigne $json dans une expression.

binary contient les fichiers, s'il y en a. Il est absent ici ; on le verra plus bas.

pairedItem indique de quel élément d'entrée celui-ci provient : { "item": 0 } veut dire « du premier élément reçu », car n8n compte à partir de zéro. n8n remplit ce champ lui-même. C'est la liaison des éléments (item linking) : grâce à elle, un nœud placé loin en aval peut retrouver, pour l'élément qu'il traite, les données que le même produit avait trois nœuds plus tôt. Le chapitre 5 montre comment s'en servir dans une expression.

Après Regrouper, l'unique élément de sortie est lié aux six éléments d'entrée :

"pairedItem": [
  { "item": 0 }, { "item": 1 }, { "item": 2 },
  { "item": 3 }, { "item": 4 }, { "item": 5 }
]

4.5Les types de données

Les valeurs de json suivent les types du format JSON :

Il n'existe pas de type date en JSON. Les dates voyagent sous forme de texte, en général au format ISO 8601 : "2026-10-05T08:52:32.150Z". Le Z final signale le temps universel. Les dates que produit le formulaire du chapitre 3 portaient au contraire le décalage horaire de l'instance, +01:00. Les deux sont exactes, mais on ne les compare pas comme du texte : le chapitre 5 apprend à les manipuler.

Un même chiffre peut être un nombre ou un texte, et la différence compte. 1500 et "1500" s'affichent pareil dans un tableau, mais le premier se multiplie et se compare comme un nombre, le second comme une chaîne de caractères : rangé par ordre alphabétique, "9500" passe après "18000". La vue Schema les distingue par une icône, # pour les nombres, T pour le texte.

Les données imbriquées

Un objet peut en contenir d'autres, et un tableau peut contenir des objets. L'élément de sortie de Regrouper en est un exemple : un objet dont le champ produits est un tableau de six objets. On atteint une valeur imbriquée en enchaînant les noms et les positions : $json.produits[0].nom donne le nom du premier produit. Faire glisser un champ imbriqué depuis l'entrée écrit ce chemin pour vous.

4.6Des éléments aux fichiers

Les données ne sont pas toujours des champs. Une facture en PDF, une photo, un tableau Excel, un export CSV sont des fichiers. n8n les appelle données binaires (binary data) et les range dans la partie binary des éléments.

Le workflow Ch04 · Fichiers transforme les six produits en un fichier CSV, puis le relit. Le nœud Convert to File, réglé sur Convert to CSV, prend tous les éléments reçus et en fait un seul fichier, produits.csv. Il rend un seul élément, dont le champ binaire s'appelle data.

Le nœud sait produire bien d'autres formats : HTML, iCal, JSON, ODS, RTF, texte brut, XLS et XLSX. Son inverse, Extract From File, lit du CSV, du HTML, de l'ICS, du JSON, de l'ODS, du PDF, du RTF, du texte, du XML, du XLS et du XLSX.

Dans les données de l'exécution, l'élément produit ressemble à ceci :

[
  {
    "json": {},
    "binary": {
      "data": {
        "mimeType": "text/csv",
        "fileType": "text",
        "fileExtension": "csv",
        "data": "filesystem-v2",
        "fileName": "produits.csv",
        "id": "filesystem-v2:workflows/uVQxHb0qh6PNaZBp/executions/98/binary_data/1ad254eb-d105-449a-b6c2-28ff9116227c",
        "fileSize": "672 B",
        "bytes": 672
      }
    },
    "pairedItem": [
      {
        "item": 0
      },
      {
        "item": 1
      },
      {
        "item": 2
      },
      {
        "item": 3
      },
      {
        "item": 4
      },
      {
        "item": 5
      }
    ]
  }
]

Sa partie json est vide : l'élément ne transporte qu'un fichier. Et ce fichier n'est pas dans l'élément. Le champ id le désigne par une référence : filesystem-v2:workflows/…/executions/…/binary_data/…. n8n a écrit le contenu sur le disque et ne fait circuler que l'adresse. On manipule ainsi de gros fichiers sans les traîner en mémoire de nœud en nœud. Sur le serveur de l'instance du livre, le fichier se trouve bien dans le volume de n8n :

$ docker exec livre-n8n-n8n-1 sh -c \
    'find /home/node/.n8n/storage -type f | head -n 2'
/home/node/.n8n/storage/workflows/uVQxHb0qh6PNaZBp/executions/98/binary_data/1ad254eb-d105-449a-b6c2-28ff9116227c
/home/node/.n8n/storage/workflows/uVQxHb0qh6PNaZBp/executions/98/binary_data/1ad254eb-d105-449a-b6c2-28ff9116227c.metadata

Le fichier sans extension est le CSV ; celui en .metadata est une petite fiche qui donne son nom, son type et sa taille. Ces fichiers suivent la vie des exécutions : ils disparaissent quand n8n purge les vieilles exécutions.

Relire un fichier, et ses pièges

Le nœud Extract From File, réglé sur Extract From CSV, relit le fichier et rend un élément par ligne : on retrouve six produits.

L'aller-retour n'est pourtant pas neutre. La vue JSON du premier élément révèle deux surprises :

sans l'option : "reference"  "nom"  "categorie"  "prix"  "stock"  …

Les nombres sont devenus du texte. "prix": "1500", entre guillemets. Un fichier CSV ne connaît que du texte : il n'a aucun moyen de dire que la colonne prix contient des nombres. Il faudra convertir ces valeurs avant de calculer ou de comparer, comme on l'apprendra au chapitre 5.

Le nom de la première colonne commence par un caractère invisible. Le fichier produit par Convert to File commence par une marque d'ordre des octets, ou BOM (byte order mark). Ce sont les trois octets EF BB BF, que certains tableurs utilisent pour reconnaître un fichier en UTF-8. Extract From File la recopie dans le nom de la première colonne, qui devient reference. L'expression $json.reference ne trouve alors plus rien, et l'écran n'en montre aucun signe, puisque le caractère ne s'affiche pas.

La parade est une option d'Extract From File : Exclude Byte Order Mark (BOM), à activer. Les noms de colonnes redeviennent propres.

4.7Erreurs fréquentes

Croire qu'un nœud traite la liste d'un bloc. Un nœud qui agit le fait une fois par élément : six produits, six messages. Pour agir une seule fois, regroupez d'abord avec Aggregate, ou activez Execute Once.

Prendre un nombre lu dans un CSV pour un nombre. Tout ce qui sort d'un CSV est du texte : "1500", pas 1500. Un nœud If qui compare ce prix à 1 000 s'arrête alors sur Wrong type: '1500' is a string but was expecting a number. Activez Convert types where required dans le nœud, écrivez {{ $json.prix.toNumber() }}, ou utilisez un format qui garde les types, comme XLSX (exercice 4).

Ignorer la marque BOM. Le premier nom de colonne d'un CSV produit par n8n commence par un caractère invisible, et $json.reference ne trouve plus rien. Retirez-la à la lecture.

Chercher un type « date ». JSON n'en a pas : une date est du texte au format ISO 8601. Pour calculer avec, il faut la convertir (chapitre 5).

Fabriquer des éléments sans lien. Un nœud Code qui crée ses éléments de toutes pièces ne remplit pas toujours pairedItem. Les expressions qui remontent le fil, comme $('Nœud').item, échouent alors en aval.

4.8Testez-vous

1. Quelles sont les trois parties d'un élément, et que contient chacune ?
2. Un nœud reçoit huit éléments. Combien de fois s'exécute-t-il en général ? Et avec Execute Once ?
3. Quel nœud transforme une liste d'éléments en un seul élément ? Lequel fait l'inverse ?
4. Où n8n range-t-il le contenu d'un fichier qui passe dans un workflow ?
5. (Chapitre 3) Le nœud Data table du chapitre 3 a écrit une seule ligne par demande de devis. Pourquoi une seule ?

En résumé

• Entre deux nœuds circule toujours une liste d'éléments. Un élément est un objet à trois parties : json, binary et pairedItem.
• La plupart des nœuds s'exécutent une fois par élément reçu ; Execute Once les limite au premier.
• Aggregate fait d'une liste un seul élément, Split Out fait de chaque case d'un tableau un élément.
• pairedItem relie chaque élément de sortie à ses éléments d'entrée ; c'est ce qui permet de remonter le fil dans une expression.
• Les types JSON sont texte, nombre, booléen, nul, objet et tableau. Les dates sont du texte, au format ISO 8601.
• Les fichiers voyagent dans binary, sous forme de référence ; n8n 2.41 range leur contenu sur le disque, dans storage.
• Un CSV transforme les nombres en texte ; celui que produit Convert to File commence par une marque BOM, à exclure à la lecture.

Exercices

Exercice 1 — Compter

Un workflow lit 40 contacts dans un tableur, puis enchaîne un nœud If qui en garde 15 dans sa branche true, puis un nœud d'envoi d'e-mail sur cette branche. Combien d'e-mails partent ? Combien partiraient si l'on activait Execute Once sur le nœud d'e-mail ? Et si l'on plaçait un nœud Aggregate avant lui ?

Exercice 2 — Le récapitulatif

Modifiez Ch04 · Éléments pour obtenir un seul élément contenant deux listes : celle des noms des produits en rupture de stock, et celle de leurs références. Quel mode d'Aggregate faut-il ? Vérifiez dans la vue JSON.

Exercice 3 — L'API qui répond en bloc

Une API de livraison renvoie un seul élément de la forme { "tournee": "T-12", "colis": [ {…}, {…}, {…} ] }. Vous voulez créer une ligne de table par colis, en gardant le numéro de tournée sur chaque ligne. Quel nœud utilisez-vous, avec quel réglage ? (Regardez l'option Include de Split Out.)

Exercice 4 — Excel

Remplacez le format CSV par XLSX dans les deux nœuds de Ch04 · Fichiers. Les nombres reviennent-ils en nombres ? Le premier nom de colonne est-il propre ? Téléchargez le fichier et ouvrez-le dans un tableur.

Corrigés

Testez-vous.

1. json, les données sous forme de champs ; binary, les fichiers que l'élément transporte ; pairedItem, l'élément d'entrée dont il provient.
2. Huit fois, une par élément. Avec Execute Once, une seule fois, avec le premier élément reçu.
3. Aggregate fait d'une liste un seul élément ; Split Out fait un élément de chaque case d'un tableau.
4. Sur le disque, dans le dossier storage du volume de n8n ; l'élément ne porte qu'une référence vers ce fichier.
5. Parce que le formulaire produit un seul élément par envoi. Le nœud Data table s'exécute une fois par élément reçu : une demande, une ligne.

Les exercices ont été vérifiés le 16 octobre 2026 sur l'instance du livre (outils/captures/essais-ch04-exercices.mjs, résultats dans exemples/ch04/exercices.json).

Exercice 1. Quinze e-mails, un par élément de la branche true. Avec Execute Once, un seul, avec le premier contact. Avec un Aggregate placé avant, un seul aussi : l'Aggregate ne laisse passer qu'un élément, qui contient la liste des quinze contacts. Dans l'essai, un appel HTTP tenait lieu d'envoi d'e-mail : les trois nœuds ont rendu respectivement 15, 1 et 1 éléments.

Exercice 2. Il faut le mode Individual Fields, avec deux champs : nom et reference. On filtre d'abord les produits dont le stock vaut 0, avec un nœud Filter. Dans la table du livre, seul le sac en raphia est en rupture :

{ "nom": ["Sac en raphia tressé"], "reference": ["SAC-006"] }

Exercice 3. Le nœud Split Out, avec Fields To Split Out sur colis et Include sur Selected Other Fields, tournee dans la liste des champs. Chaque élément de sortie porte alors le numéro de tournée, et le colis rangé sous le champ colis :

{ "colis": { "numero": "C-301", "quartier": "Akwa" }, "tournee": "T-12" }

Attention à ce détail, vérifié sur l'instance : sans Include, Split Out met les champs du colis au premier niveau (numero, quartier), mais dès qu'on inclut d'autres champs, il les range sous colis. Dans le nœud qui écrit la ligne, on désigne donc {{ $json.colis.numero }} et {{ $json.tournee }}.

Exercice 4. Oui : avec XLSX, prix et stock reviennent en nombres (1500, 120), et le premier nom de colonne est propre, sans marque BOM. Un tableur garde les types de ses cellules, ce que le CSV, simple texte, ne sait pas faire. Les dates restent du texte, comme dans tout JSON.

Pour aller plus loin

Dans n8n. Le bouton View d'une donnée binaire l'affiche dans le navigateur quand c'est possible (image, PDF, texte) ; Download l'enregistre. L'onglet Settings de chaque nœud regroupe Always Output Data, Execute Once et les réglages d'erreur, qu'on retrouvera au chapitre 9.

En ligne. Dans la documentation, « Build › Work with data » réunit les pages « Understand n8n's data structure », « Link data items » et « Work with files and images ». Les fiches des nœuds Aggregate, Split Out, Convert to File et Extract From File détaillent chacun de leurs réglages.