Conteúdo

Estrutura de dados no n8n: como items, JSON e nós lidam com vários dados

O conceito mais importante e que mais costuma causar dúvidas ao aprender n8n é: os nós não passam um único dado entre si, mas uma lista (items) composta por vários dados.

Como são os items

A saída de um nó aparece assim na visualização JSON:

[
  { "name": "Xiaoming", "email": "ming@example.com" },
  { "name": "Xiaohua", "email": "hua@example.com" },
  { "name": "Xiaomei", "email": "mei@example.com" }
]

São 3 items. Internamente, cada item no n8n é, na verdade:

{
  "json": { "name": "Xiaoming", "email": "ming@example.com" },
  "binary": { }
}

json: dados comuns; $json nas expressões se refere a eles.
binary: dados de arquivos (imagens, PDFs, planilhas etc.); só aparece quando você precisa processar arquivos.

Cada nó é executado uma vez para cada item

Esta é a regra mais importante do n8n. Suponha que o nó anterior gere 3 dados e que o próximo seja o nó “Send Email”:

[Google Sheets] ──3 items──▶ [Send Email]
                               Envia 3 e-mails (um para cada item)

Você não precisa escrever um loop: o n8n processa tudo automaticamente. No nó Send Email, {{ $json.email }} será ming@example.com ao processar o primeiro item, hua@example.com ao processar o segundo, e assim por diante.

O número exibido no canto superior direito do nó (por exemplo, 3 items) indica quantos dados foram gerados.

Um nó processa vários dados após Split Out — Depois da execução, as conexões mostram quantos items foram passados em cada trecho; o nó If divide os dados em duas saídas: true / false

“Por que minha mensagem foi enviada 5 vezes?”

A causa mais comum é que o nó anterior gerou 5 items, então o nó “Enviar mensagem” seguinte foi executado 5 vezes. Soluções:

Se você quer executar apenas uma vez: ative Execute Once em Settings do nó para processar somente o primeiro item.
Se você quer combinar vários dados em uma única mensagem: primeiro use o nó Aggregate ou Summarize para reuni-los em um item.

Nós comuns para transformar dados

Nó	Função	Exemplo
Split Out	Divide um array de um dado em vários dados	A API retorna `{ "orders": [...] }`; divide para criar um item por pedido
Aggregate	Combina campos de vários dados em um array, formando um único item	Combina 10 pedidos e envia um resumo de uma só vez
Summarize	Agrupa e calcula estatísticas (soma, contagem, média)	Calcula o total de vendas por região
Limit	Mantém somente os primeiros N dados	Processa apenas os 5 artigos mais recentes
Remove Duplicates	Remove dados duplicados	Envia apenas um e-mail para cada endereço
Sort	Ordena	Ordena por data
Filter	Mantém apenas os dados que atendem a uma condição	Processa apenas pedidos com valor acima de 1000
Edit Fields (Set)	Adiciona, altera ou remove campos	Mantém apenas os campos necessários

Exemplo: dividir o array retornado por uma API

Os dados obtidos com HTTP Request muitas vezes vêm como “um item contendo um array”:

[
  {
    "results": [
      { "id": 1, "title": "Artigo A" },
      { "id": 2, "title": "Artigo B" }
    ]
  }
]

Nesse caso, o nó seguinte será executado uma vez. Adicione um nó Split Out, informe results no campo, e os dados serão divididos em dois items:

[
  { "id": 1, "title": "Artigo A" },
  { "id": 2, "title": "Artigo B" }
]

Split Out divide um array em 3 dados — Split Out: INPUT contém 1 dado com um array results; OUTPUT passa a conter 3 dados

Vinculação de items (item linking)

O n8n registra qual dado de entrada originou cada dado de saída. Assim, nos nós seguintes, você pode acessar o valor do mesmo dado em um nó anterior:

{{ $('Google Sheets').item.json.name }}

Isso significa: “o valor de name no nó Google Sheets correspondente ao dado atual”. Veja a explicação completa em Tutorial de expressões.

Várias entradas: nó Merge

Quando um fluxo se divide em dois caminhos e você precisa reuni-los, use o nó Merge:

Modo	Descrição
Append	Junta os dados dos dois caminhos
Combine by matching fields	Combina os dados por campos em comum (como um JOIN em SQL), por exemplo, usando email para relacionar dados de clientes e pedidos
Combine by position	Combina o primeiro item com o primeiro, o segundo com o segundo
Choose branch	Aguarda a conclusão dos dois caminhos e então gera os dados de apenas um deles

Dados binários (arquivos)

Ao ler arquivos, baixar imagens ou receber anexos, os dados ficam em binary. Na aba Binary da seção OUTPUT, você pode visualizá-los ou baixá-los. Nós comuns:

Extract from File: extrai o conteúdo de arquivos CSV, Excel, PDF ou JSON e o transforma em items
Convert to File: transforma items em arquivos CSV, Excel ou JSON
Read/Write Files from Disk: lê e grava arquivos no servidor (por padrão, o n8n 2.x permite acesso somente a pastas específicas)

Resumo

Os nós passam arrays de items entre si
Cada nó é executado uma vez para cada item; você não precisa escrever um loop
Use Split Out para dividir, Aggregate para agrupar e Merge para combinar
Para evitar execuções repetidas, ative Execute Once ou combine os dados antes

Atualizado 12 de outubro de 2026