Loop node
The Loop node iterates over something and emits one output row per iteration. It has three modes: for (numeric range), rows (each input row becomes one iteration), and foreach (expand an array-typed field per row).
When to use
- You have a list-typed field per row and need one output row per element (
{ orderId, lineItems: [...] }→ one row per line item). - You want to expand each input row into N by iterating over a range or a nested list.
- You need a bounded, deterministic loop; use Fork for parallel branch execution instead.
Ports
| Port | Direction | Kind | Notes |
|---|---|---|---|
in | in | data | Input rows. |
out | out | data | One row per iteration with iteration metadata attached. |
error | out | control | Fires when an iteration's exitExpr throws. |
notify | out | control | Notification policy port. |
Configuration
- Loop mode.
for— numeric range:start,count,step.rows— one iteration per input row.itemFromFieldoptionally derives the alias.foreach— expandlistFieldper input row.
- itemField (default
dl_loop_item). Column name to attach the current item under. - indexField (default
dl_loop_index). Column name to attach the 0-based iteration index. - maxIterations (default 10 000). Hard cap on the total iteration count across the pass.
- exitExpr. Optional early-exit expression. When truthy for an iteration, the loop stops. Great for "process up to N rows or until we hit a marker".
- keepOriginal (default on). When on, the emitted row spreads the input row plus the iteration metadata. When off, only the metadata columns appear.
- reportEvery (default 0). If set to N, every Nth iteration logs
LOOP(name): iterated N item(s)toctx.log.
Runtime behaviour
- Iterations run sequentially in-process.
- The Loop executor returns an
iterationscount on its output, which the runtime records onctx.metrics[node.id].iterations. The run viewer surfaces it as an iteration chip on the Loop node's row and appends. N iteration(s)to the payload card header. reportEvery: 1logs on every iteration; useful for a small run when you want visibility into the loop's progress.
Failure modes
- exitExpr throws. The iteration routes to
error; the run continues past the loop. - maxIterations hit. The loop stops silently at the cap; no error is fired. Set
maxIterationsdeliberately for unbounded lists.