n8n-loops-official

n8n のループ

「ループ」には3つの意味があり、それぞれ異なる仕組みに対応します。

1. 「すべてのアイテムに対して、このノードを実行する。」 デフォルトです。ほとんどのノードは自動的にループするため、何もする必要はありません。
2. 「すべてのアイテムをまとめて、このノードを 1回だけ 実行する。」 executeOnce 設定（単一のブール値）を使います。
3. 「反復の間に制御フローを挟み、明示的なバッチでアイテムを処理する。」 Loop Over Items ノード（旧称 Split In Batches）を使います。

ページネーションのある API には、HTTP Request ノードに組み込みのページネーション機能があります。手作業でページ数を数えるループを作るより、ほとんどの場合こちらが適しています。

モデル：アイテムは配列です

データは各 { json: {...}, binary?: {...} } の形式のアイテムが並ぶ配列としてノード間を流れます。50アイテムなら、50要素の配列です。

デフォルトでは、ノードはアイテムごとに1回実行されます。入力アイテムが50個ある HTTP Request は、50件のリクエストを送信し、結果アイテムを50個出力します。これが、多くのワークフローで使われている暗黙のループです。

入力配列がループです。 配列を制御して、反復を制御します。

必須事項

ノードをアイテムごとではなく、実行ごとに1回だけ実行する場合は、必ず executeOnce: true を設定してください。データセット全体をまたいで集約する式、つまり $input.all() / $('Node').all() と .map() / .filter() / .reduce() を組み合わせた式も該当します（設定しないと、上流にアイテムが N 個ある場合、集約処理が N 回実行され、下流に同じ結果が N 個出力されることがよくあります）。通知、集約書き込み、要約メッセージも該当します。

例外ケース： .all() と別のノードの .item（アイテムごとの検索。例：$('Get Tags').all().filter(tag => $('Search Posts').item.json.tag_ids.includes(tag.json.id))）を組み合わせる処理は、実際にアイテムごとに行う処理なので、executeOnce はオフのままにしてください。詳しくは n8n-expressions-official スキルの executeOnce セクションを参照してください。

基本的な推奨事項

• デフォルトの反復で足りる場合は、ループを作らないでください。 ほとんどのノード（HTTP Request、ネイティブのサービスノード、Set、IF/Switch）は、入力アイテムごとに自動的に1回実行されます。入力が N 個なら、実行も N 回です。N 件の HTTP リクエストを送信したり、N 件のレコードを作成したりするには、ソースをそのノードに接続するだけです。反復ごとの制御が必要でない限り、Loop Over Items は使わないでください。（注：例外は Execute Workflow です。デフォルトでは、すべてのアイテムをまとめた単一のバッチとして実行されます。mode: 'each' については n8n-subworkflows-official を参照してください。）
• ページネーションのある API には、HTTP Request の組み込みページネーションを使ってください。 API が特別な仕様でない限り、Loop Over Items と手動の $pageCount で代用しないでください。references/HTTP_PAGINATION.md を参照してください。
• Loop Over Items は、明示的なバッチ処理や反復ごとの制御（レート制限、バッチごとのエラー復旧、状態を持つチャンク、ポーリング）に使います。references/LOOP_OVER_ITEMS.md を参照してください。
• アイテムごとの反復は逐次実行であり、並列実行ではありません。 並列に見える分岐でも、次のアイテムが開始される前に、現在のアイテムの処理が完了します。実際の並行処理パターンについては、n8n-subworkflows-official を参照してください。

判断フロー：どの仕組みが必要ですか？

Need to do something for each item?
├── Default per-item iteration is enough
│   └── Just connect the node. Done.
│
├── The node should run once total, not once per item?
│   └── Set executeOnce: true on the node
│
├── Paginated API (multiple HTTP calls to fetch all pages)?
│   └── Use HTTP Request's Pagination option (see references/HTTP_PAGINATION.md)
│
├── Need explicit batching (rate limit, chunk size, per-batch error handling)?
│   └── Use Loop Over Items node (see references/LOOP_OVER_ITEMS.md)
│
└── Need to recurse / repeat with state until a condition is met?
    └── Loop Over Items with Reset, OR a sub-workflow that calls itself.
        Both are advanced patterns; see references/LOOP_OVER_ITEMS.md.

executeOnce：1回だけ実行する設定

すべてのノードの「Settings」タブには、Execute Once の切り替えがあります。有効にすると、ノードは最初の入力アイテムだけを使って1回実行されます。SDK コードでは、次のように executeOnce: true を設定します。既存のワークフローでは、update_workflow の setNodeSettings を使って適用します（n8n 2.24.0+）。

{
    name: 'Aggregate Slack',
    type: 'n8n-nodes-base.slack',
    parameters: { /* ... */ },
    executeOnce: true,
}

使用する場合：

• 通知と集約書き込み。 100個のアイテムが届いたからといって、「要約メッセージ」を100回送信すべきではありません。
• カウンター、合計値、レポート。 $input.all().length などを計算する処理は、1回だけ実行する必要があります。
• $input.all() / $('Node').all() で配列全体を集約する式。 そうしないと、集約処理が上流のアイテムごとに実行されます。（別のノードの .item で絞り込む .all() を使ったアイテムごとの 検索 は例外です。n8n-expressions-official を参照してください。）

使用しない場合：

• アイテムごとの処理。 アイテムごとに通知を1回送るのはデフォルトの動作で、通常は適切です。
• アイテムごとに振り分ける HTTP リクエスト。 アイテムごとに1回ずつ呼び出す必要があります。

最もよくある間違いは、集約ノードに executeOnce を設定し忘れ、アイテムを振り分けた後に同じメッセージが50回送信されることです。

暗黙のループが問題になるとき

項目ごとのデフォルトの反復処理は、問題が起きるまでは便利です。よくある想定外の動作を紹介します。

「単一」の設定ノードが項目ごとに実行される

ファンアウトの後にある Set ノードは項目ごとに1回実行されるため、同じ定数がN個生成されます。通常は問題ありませんが、負荷の高い式（長い JSON.stringify、Luxon の解析など）はN回実行されます。Set をファンアウトの前に移動するか、executeOnce: true を設定してください。

集約用の Code ノードがN回実行される

$input.all() を読み取って合計を計算する Code ノードは、executeOnce: true がないと上流の項目ごとに1回実行され、同じ項目をN個生成します。executeOnce: true を設定してください。

Webhook への応答が2回実行される

最も厄介なケースです。Respond to Webhook は入力項目ごとに実行され、2つのブランチがマージなしで合流すると2回実行されます。最初の応答だけが有効になり、残りはエラーとして記録されます。先にマージするか、応答ノードに到達するブランチが1つだけになるようにしてください。n8n-node-configuration-official の references/MERGE_NODE.md を参照してください。

要約を1つだけ作りたいのに、LLM 呼び出しがN回実行される

集約用の Code ノードと同じパターンです。プロンプトに $input.all() を使う LLM ノードは、executeOnce: true がないと同じ呼び出しをN回行い、N倍のトークンを消費して、同じ回答をN個返します。

Loop Over Items を使うべきとき

デフォルトの反復処理で、ほとんどのケースに対応できます。次のような場合は Loop Over Items を使ってください。

• レート制限。 「一度に10件処理し、バッチ間に1秒待機する。」
• 配列ボディを使ったバッチ API 呼び出し。 「50件ずつ /bulk に送信する。」
• バッチごとのエラー処理。 「バッチが失敗したら、記録して処理を続行する。」
• 状態を保持する反復処理。 「各反復処理が、前回の出力に依存する。」
• 長時間実行ジョブのポーリング。 「開始し、完了するか上限に達するまで30秒ごとにステータスを確認する。」reset: true と $runIndex の上限値を使います。
• 集約を伴う項目ごとのマルチブランチ処理。 「入力ごとに変換処理を並列実行し、マージしてから集約する。」完了出力（インデックス0）に結果が含まれます。

配線の詳細、出力インデックスに関する注意点（出力0 = 完了、出力1 = ループ）、実例については references/LOOP_OVER_ITEMS.md を参照してください。

Loop Over Items を使うべきでないとき

最もよくある誤った判断は、「次のステップに進む前にすべての項目が終わるのを待つ必要があるので、Loop Over Items を追加して done 出力を使おう」です。**そのために Loop Over Items を使う必要はありません。**項目ごとのデフォルトの反復処理は、すでに完了を待ちます。各項目は下流のチェーン全体を通過してから次の項目が開始され、ループ後のノードが「早く」実行されることはありません。

この誤りを解消する方法は、ほとんどの場合、Loop Over Items ノードを削除し、ほかは何も変えずにリリースすることです。これは以下のシナリオ1に当たり、大半のケースをカバーします。

4つのシナリオはそれぞれ独立しています。すべてが Loop Over Items を「置き換える」選択肢ではなく、別々の判断として読んでください。ほとんどの構成はシナリオ1に当てはまり、それで完了です。シナリオ2と3は、それぞれ固有の目的がある場合にのみ検討します。シナリオ4は、Loop Over Items を実際に使う意味がある限定的なケースです。

シナリオ1：項目ごとのデフォルトの反復処理（デフォルトで、最も一般的）

ソースがN個の項目を出力し、項目ごとのプロセッサーがN回実行され、下流のチェーンへ続きます。**Loop Over Items も、executeOnce も、Aggregate も不要です。**ノードを接続するだけです。

[Source: 20 items]
  → [Per-item processor]   # default iter, runs 20 times
  → [Next step]            # runs after each item, in order

「すべての項目を待つため」または「次のノードを各項目に対して実行するため」に、ここへ Loop Over Items + done を追加した場合は、Loop Over Items ノードを削除し、ソースからプロセッサーへ直接つないでください。**代わりに何かを追加する必要はありません。**デフォルトの反復処理で、すでに目的を果たせます。例外は Execute Workflow（サブワークフロー）です。デフォルトでは全項目をまとめて1つのバッチとして処理するため、項目ごとに呼び出すには Loop ではなく、そのノードに mode: 'each' を設定する必要があります。n8n-subworkflows-official を参照してください。

シナリオ 2：後続ノードを合計 1 回だけ実行する（executeOnce: true）

シナリオ 1 とは独立しています。1 アイテムごとではなく、1 回の実行につき 1 回だけ処理する特定の後続ノードがある場合に限ります。たとえば、20 件の論文を処理した後に送るダイジェストメール、ループ後に 1 回だけ書き込むサマリー、最後に送る Slack 通知です。

そのノードに executeOnce: true を設定します。ノードは上流のすべてのアイテムを受け取りますが、実行は 1 回だけです。これはノードごとの設定であり、Loop の代替ではありません。シナリオ 1 のアイテムごとの処理ノードは引き続き N 回実行され、この後続ノードだけが 1 回に集約されます。

シナリオ 3：ノードがアイテムを単一の配列として必要とする（Aggregate）

シナリオ 1 とは独立しています。後続ノードの入力仕様が、アイテムごとの呼び出しではなくリストである場合に限ります（例：JSON 配列のボディを受け取るノード、リスト全体を必要とする LLM プロンプト）。

Aggregate ノードを使って、アイテムごとのストリームを、配列を含む 1 つのアイテムに集約します。これも Loop の代替ではありません。

シナリオ 4：本当のバッチ処理（Loop Over Items が役立つ唯一のケース）

レート制限（N 件ずつ処理し、バッチ間に Wait を挟む）、分割した一括 API 呼び出し（50 件の配列を /bulk に POST する）、バッチごとのエラー処理、reset: true と $runIndex の上限による実行時間の長いジョブのポーリング、各バッチが前回の出力に依存するステートフルな反復処理。

「アイテムの完了を待つ」だけでは該当しません。デフォルトの反復処理ですでに実現できます。

すぐに判断するには

Loop を使う理由が「アイテムを待つ／各アイテムで実行する」だけなら、シナリオ 1 に該当します。Loop を削除してください。代わりに executeOnce や Aggregate を追加しないでください。これらは別の問題を解決するもので、それぞれのシナリオに該当する場合にのみ追加します。

HTTP ページネーションを使うべき場合

よくあるページ形式は次の 3 種類です。

• レスポンス内の次ページ URL。 各レスポンスに next リンクが含まれます。
• ページ番号／カーソルのパラメーター。 呼び出しごとに ?page=N または ?cursor=... を増やします。
• 空のページまたは特定のステータスで停止します。

HTTP Request は Pagination オプションで、これらすべてに標準で対応しています。モードを設定し、次ページの式を指定すると、ノードが内部でループし、すべてのページのアイテムを含む単一の出力配列を返します。

API が組み込みモードでは表現できない処理を必要としない限り、Loop Over Items と手動の $pageCount で作り直す必要はありません。

references/HTTP_PAGINATION.md を参照してください。

サブワークフローの再帰

本当に再帰的な処理（ツリーの走査、バックオフ付きの再試行、「これとその子を処理する」など）には、Reset を使った Loop Over Items よりも、自己呼び出しするサブワークフローのほうがシンプルです。入力パラメーターで再帰の状態を受け渡します。

Sub-workflow: Walk Tree
  inputs: { node_id, depth }
  body: process node, look up children, for each child call self with depth+1

再帰の深さに注意してください。n8n にはネストされた実行の上限があります。深い再帰では、真の再帰よりもキューとフラットなループを使うほうが適しています。

参照ファイル

ファイル	読むタイミング
references/LOOP_OVER_ITEMS.md	Loop Over Items ノードの設定、バッチ処理、レート制限、ステートフルな反復処理を行う場合
references/HTTP_PAGINATION.md	ページネーションに対応した API の呼び出し、HTTP Request のページネーションモードの設定を行う場合

アンチパターン

アンチパターン	問題点	対処法
デフォルトのイテレーションで既に繰り返されるのに、「ループさせる」ために Loop Over Items を追加する	メリットがないのにワークフローが読みにくくなり、ループ出力と完了出力の接続を誤りやすくなります	ノードを直接接続し、デフォルトのイテレーションに任せます
executeOnce を設定せずに Code ノードで集約する	同じ集約処理が N 回実行され、同一のアイテムが N 個出力されます	executeOnce: true を設定します
Loop Over Items と $pageCount を使った手動のページネーションループ	HTTP Request が標準で行う処理を再実装することになり、終了条件も壊れやすくなります	HTTP Request の Pagination オプションを使います
要約を送りたかったのに、アイテムごとに Slack メッセージを送信する	Slack チャンネルがメッセージであふれ、レート制限に達し、気まずい思いをします	Slack ノードに executeOnce: true を設定し、上流で要約を作成します
2 つのブランチがどちらも Respond to Webhook に到達する	2 回応答し、呼び出し元にエラーが返されます	応答ノードの前でブランチをマージするか、到達するブランチが 1 つだけになるようにします
Reset を設定した Loop Over Items に明確な終了条件がない	無限ループになり、実行が強制終了されるまで n8n がメモリを消費します	必ず明確な終了条件を設定します。ページ分割された API には HTTP のページネーションを使用してください
同じワークフロー内で Loop Over Items を入れ子にする	実行時に問題が発生しますが、検証は通過します	内側のループをサブワークフローに移し、外側のイテレーションごとに呼び出します。n8n-subworkflows-official の mode: 'each' を参照してください