Merge / Loop Over Items / Split Out / Aggregate: working with many items

Why these three nodes matter

Once you have built a few workflows you will run into these situations:

• You split with IF and cannot work out how to join the paths back. The IF node splits the data down a true / false pair of paths. Each side finishes its own work and you want one summary notification at the end — but the two paths keep running separately, and nothing you try brings them back together.
• The Airtable / Notion API allows 5 calls a second and you feed it 500 items at once. Push them all in and the node is knocked back with 429 Too Many Requests halfway through: the early ones went in, the rest never ran, and patching that up is painful.
• The API returns one item with a results array inside, and the nodes downstream cannot reach it. You saw this trap in Chapter 9 — { total: 5, items: [...] } counts as 1 item, so the Slack node downstream sends once instead of 5 times.
• Two APIs each return half the data and you need a join to get the whole picture. One side has the customer details, the other the order amounts, both on the same customer_id, and you want them stitched into one report.

These four problems are solved by a handful of nodes: Merge (joining paths), Loop Over Items (formerly Split In Batches, for batching), Split Out (an array becomes several items) and Aggregate (several items become one array) — the last two used to be Item Lists and are separate nodes now. Learn these and your workflows move on from "toys" to "things the business can run on".

What each node does, in one table

Get each node's place straight first, and you will know which one to reach for as soon as a situation shows up:

The Merge node: four modes, and three more choices under Combine

The Merge node always needs two inputs (you see two connector dots when you draw a connection to it). The Mode dropdown has four options — this is the structure n8n moved to after 2024, and it is not the "three modes" older tutorials describe:

Once you pick Combine, there are three strategies under Combine By:

With Matching Fields selected, Output Type decides the kind of join (all five are there):

• Keep Matches — only items matched on both sides are output (inner join).
• Keep Non-Matches — only unmatched items are output (for finding the difference, as in "which customers have never ordered").
• Keep Everything — everything is kept, and unmatched fields come out as null (full outer join).
• Enrich Input 1 — Input 1 leads, and the fields from Input 2 that match are pasted on (left join).
• Enrich Input 2 — Input 2 leads, and the fields from Input 1 that match are pasted on (right join).

Loop Over Items (formerly Split In Batches): batch the work to stay under rate limits

The situation: the Airtable API allows at most 5 requests a second, and your Google Sheet has 500 customer rows to write into Airtable. Wire it straight through and after the 5th item you start collecting 429s, with the remaining 495 all failing. This is where Loop Over Items comes in.

Its behavior is a little unusual and confusing the first time you meet it: this node forms the loop itself.

On the canvas it looks like this (the nodes on the loop side have to draw a connection back to the Loop Over Items node, which is what makes the loop):

Google Sheets (500 items)
  ↓
Loop Over Items (Batch Size = 5)
  ├─ loop → Airtable Create → Wait 1 second ──┐
  │                                            │
  │←─────── back to the Loop Over Items node ──┘
  │
  └─ done → Slack "500 records processed"

Loop Over Items does not produce a "progress bar" message itself, but every round of the loop passes through the same nodes — to report progress along the way, add a Slack node on the loop branch that sends "batch N done, M batches left".

Split Out / Aggregate: flatten an array, or collect items back into one

Split Out: an array inside one item → several items

Classic use: the Gmail node picks up a message whose binary or json holds an attachments array with 5 attachments. The whole thing counts as 1 item, and you want to run an upload to Google Drive once per attachment.

After the split the output goes from 1 item to 5 items, and every node downstream runs 5 times. This is the answer to the point in Chapter 9 that "n8n items and a JSON field called items are two different things" — Split Out turns a JSON array into n8n items.

Aggregate: several items → one array inside a single item

The opposite operation. Five items have been processed and you want to collapse them into one daily summary sent as a single email. Add an Aggregate node and pick one of the two Aggregate options:

• Individual Fields — aggregates only the fields you name, with Rename Field to change the name and Merge Lists to flatten nested arrays.
• All Item Data (Into a Single List) — packs every item's whole json into one big array, with Include / Exclude lists to allow or block fields.

Sort (sorting, SQL ORDER BY), Limit (take the first N, SQL LIMIT), Remove Duplicates (deduplication, SQL DISTINCT) and Summarize (grouped statistics, SQL GROUP BY plus aggregate functions) are each their own node now too — search for whichever one you need.

Worked example: one Slack reminder per Google Sheet row

This workflow shows the case where "the items are expanded already, so you do not need Loop Over Items at all" — Google Sheets Read turns each row into an item by itself. Treat it as a warm-up.

1. Add a Manual Trigger

   Create a workflow and pick Trigger manually as the first node. Pressing Execute Workflow then runs it once.

2. Add a Google Sheets node

   Wire on a Google Sheets node and set Operation to Get Rows in Sheet. Connect the credentials (Chapter 2), then pick your spreadsheet and sheet. Say the spreadsheet is called "Customer list", has 10 rows, and its fields are name, email and due_date.

3. Execute step and confirm 10 items arrive

   Press Execute step on the Google Sheets node. The top of the output panel on the right shows 10 items — check the count is right. Switch to the Table view to read each row.

4. Add a Slack node

   Wire on a Slack node, set Operation to Send Message and pick a channel (#billing-reminder, for example). Switch the Text field to Expression mode and enter:

   Statement reminder for {{ $json.name }}. Due {{ $json.due_date }} — please take care of it.

5. Execute the whole workflow once

   Press Execute Workflow at the top right. The Slack node's output panel shows 10 items — 10 messages sent, one per row. Check the channel to confirm 10 actually arrived.

6. Save it

   Save at the top right. From then on, pressing Execute Workflow sends another round. To send it automatically on the 1st of each month, swap the Manual Trigger for a Schedule Trigger (Chapter 10).

Worked example: split the array an API returns and act on each entry

This is where Split Out belongs. Call a public API (https://jsonplaceholder.typicode.com/users, for example) and it returns one whole array of 10 users — what n8n receives is 1 item whose field is an array. To send a Slack notification per user, you need Split Out.

1. Manual Trigger + HTTP Request

   Pick a Manual trigger. Wire on an HTTP Request node, set Method to GET and URL to https://jsonplaceholder.typicode.com/users. Run it once with Execute step.

2. Check the output: 1 item with an array inside

   The top of the output panel shows 1 item (not 10). Switch to the JSON view and expand it: the whole response is an array. As it stands, any node downstream would run once — wrong, we want it to run 10 times.

3. Add a Split Out node

   Wire on a Split Out node (search "split out" and it comes straight up; the "Item Lists → Split Out Items" of older tutorials is this standalone node now). Put the field holding the array in Fields To Split Out — if HTTP Request puts the whole array in data or at the root, use the path that matches (read the real path off the output panel when you test it).

4. Execute step and confirm 10 items

   Press Execute step on the Split Out node. The top of the output panel shows 10 items — one row per user. Switch to the Table view and check that name and email both have values.

5. Wire on a Slack node to notify per item

   Wire on a Slack node with Send Message and set Text to Welcome {{ $json.name }} ({{ $json.email }}). Run Execute Workflow once → the Slack channel receives 10 welcome messages.

6. (Advanced) Aggregate back into one summary

   Add an Aggregate node after the Slack node, set Aggregate to Individual Fields and Field To Aggregate to name (Rename it to names if you like). The output is back to 1 item, with a field holding an array of 10 names. Then wire on a Gmail node that sends "Processed these 10 users today: {{ $json.names.join(', ') }}" — one summary email, instead of 10 alerts flooding the inbox.

Four common combinations

Knowing a single node is only the start; the real strength is in "two or three of them together". You will reach for these combinations most weeks:

Every one of these is worth trying on the practice workflow from Chapter 8 first: get it running there before you point it at real business work.

Common pitfalls

1. Merge Combine · Position loses half the data

   Combine By = Position means "align by position" — with 3 items on Input 1 and 5 on Input 2, the output has only 3 (the shorter side wins) and the last 2 are simply dropped. To keep everything, switch to Combine By = Matching Fields with Output Type Keep Everything, or use Append mode to stack them and work from there.

2. Loop Over Items never stops and runs forever

   Two common causes: (a) the nodes on the loop branch are not wired back to the Loop Over Items node — the loop runs one round, the rest of the data is dropped, and nothing actually errors; wire it to the done branch by mistake instead and things get strange; (b) Options → Reset is on while new items keep arriving upstream (a Webhook trigger, for example), so each arrival counts as a fresh round. Leave it off unless you are building a long-running service.

3. Split Out runs and the output is identical

   Nine times out of ten Fields To Split Out is wrong: (a) the field name is misspelled (case, singular vs plural); (b) you entered a field inside the array rather than the array itself; (c) the field is not an array at all but an object. Switch to the Schema view on the upstream node, find the field whose type is array, and paste its full path (data.results, for example) in.

4. The item order changes after a Merge

   Each mode has its own ordering rule: Append guarantees all of Input 1 first and all of Input 2 after; Combine · Position guarantees the same index lines up; Combine · Matching Fields orders by the order the keys appear in Input 1 — if you need a particular order, put a Sort node before or after the Merge.

5. The Merge node sits there and never runs

   Merge only runs when both inputs have data. After an IF split, if no item goes down the true branch (every condition came out false), Merge waits forever. The fix: put a No Operation, do nothing node on the empty branch (it changes no data, it just carries the connection), or use the IF node's Fallback Output so something reaches both Merge inputs.

6. Loop Over Items with a Wait, but the wait is not what you expected

   The seconds on a Wait node mean "this item waits N seconds here before it moves on" — with Batch Size = 5, the 5 items in one batch reach Wait at nearly the same moment and then each waits 5 seconds (not one 5-second wait for the batch). For "5 seconds between batches", keep Batch Size at 5 and Wait at 5, then test it and read the timestamps of the requests that actually went out.

FAQ