Iteration Node
Express map-over-collection inside a visual workflow as an explicit Iteration node that runs a subgraph once per element of an input array, with bounded, deterministic, observable execution.
Intent & Description
🎯 Intent
Express map-over-collection inside a visual workflow as an explicit Iteration node that runs a subgraph once per element of an input array, with bounded, deterministic, observable execution.
📋 Context
A team builds workflows on a visual canvas — Dify, Coze, n8n, or a similar low-code platform — where some part of the work must be applied to every element of a list: every retrieved chunk, every search result, every uploaded file, every row in a spreadsheet. The team wants the iteration itself to be visible on the canvas alongside the rest of the flow, so failures and timings can be inspected per element rather than hidden inside a black box.
💡 Solution
- Define an Iteration node with an input array, an inner subgraph that runs once per element with the element bound to a parameter, and an output array of per-element results. - The runtime may execute elements sequentially or in parallel up to a configured concurrency limit. - Each iteration is logged with its index; failures surface per-element rather than collapsing the whole node. - Pair with map-reduce (the algorithmic shape), visual-workflow-graph (the surrounding canvas), and parallelization (when concurrency matters).
Real-world Use Case
- Work must be applied to every element of a list and bounded by the list length.
- Per-element failures need to be inspectable.
- The surrounding workflow is visual and the iteration should remain visible.
- Sequential or bounded-parallel execution suffices.
Source
Advantages
- Iteration is structural and bounded — no LLM stopping condition required.
- Per-element failures and timings are visible on the canvas.
- Sequential vs parallel execution is a node parameter, not a code change.
- Nests cleanly inside larger visual workflows.
Disadvantages
- Large input arrays multiply token cost linearly.
- Nested iteration without a cap can blow up step counts.
- Per-element sub-workflow state can bleed into shared variables if not scoped carefully.
- Parallel execution can hit upstream rate limits.