> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bringits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# For

> Iterate a JSON array sequentially: PARSE, optionally ending in one sink, per item

The For command (Command Type: `EXECUTION_FLOW`, id **1101**) walks a JSON array on the previous command's `data` field, one element at a time. Each iteration runs the nested **body**: allowlisted [PARSE](https://docs.bringits.com/stream/commands/parse.md) commands, optionally ending with one [sink](https://docs.bringits.com/stream/commands/sink.md). With a sink, each element is published as its own sink payload; without one, For only transforms and collects the results. For does **not** create Items or set `children`.

## Command Type

**Command Type:** `EXECUTION_FLOW`

**Command Type ID:** 1101

## Input

`data` from the previous command **must already be a JSON array**. For has no selector of its own.

| Previous `data` | What to do |
| - | - |
| Bare array, e.g. `[{ "id": 1 }, { "id": 2 }]` | Pass it straight into For |
| Envelope, e.g. `{ "events": [...] }` | Run a PARSE extract onto `data` **before** For |
| HTTP parallel 1002 / 1004 output `{ "data": { "aggregatedResults": [...] } }` | The command result's `data` is `{ "aggregatedResults": [...] }`. Extract `aggregatedResults` onto `data` **before** For |

> [!WARNING]
>
> If `data` is an object, `null`, or a scalar, For fails **before any sink runs**. Extract the array first.

## Parameters

| Parameter | Type | Description | Required |
| - | - | - | - |
| **body** | Array of Command | Commands run once per array element. PARSE transforms/extracts/filters (not [Sleep](https://docs.bringits.com/stream/commands/parse/sleep.md) 1008) and at most one SINK, which must be last. Must not be empty. HTTP, If-Else, nested For, Browser, Android, WebSocket, Generate, and Validation are rejected on save. | Yes |

There is no selector field and no operator-configurable iteration cap. The cap is **1000** elements.

## Locals

Each iteration binds these **local** variables (they do not write to `state`):

| Local | Value |
| - | - |
| **item** | Current array element |
| **index** | Zero-based iteration index |
| **parent** | The array For is iterating |

[JSONata](https://docs.bringits.com/stream/commands/parse/jsonata.md) **1022** receives the **current item** as its input. The same names are also available in `local_variables` (`${local.item}`, `${local.index}`, `${local.parent}`) and in the JSONata environment.

Copy envelope fields you still need (for example a bookmaker id) into `state` **before** you extract the array onto `data`.

## Output

For returns the same shape as HTTP parallel 1002 / 1004:

```json theme={null}
{
  "data": {
    "aggregatedResults": [ /* one entry per input element, in input order */ ]
  }
}
```

Each entry is the body's result for that element (or the element itself if the body returned nothing). When the body throws for an element, its slot holds the failure instead:

```json theme={null}
{ "index": 3, "item": { "id": "evt-4" }, "error": "reason the body failed" }
```

Filter on `error` after For to separate failed elements from results, the same way as failed requests in HTTP parallel 1002.

For does not create Items and does not set `children`. Hash, miss, and retry stay on the listing Item. To fan out into `children`, add an explicit PARSE **after** For.

Commands **after** For are allowed, including another PARSE over `aggregatedResults` or another sink. A sink inside the body **and** a sink after For is **two deliveries** of related data.

## Iteration rules

| Input | Job status | Sinks |
| - | - | - |
| Empty array `[]` | VALID | 0 publishes. `iterationCount` is 0. |
| Not an array | INVALID | 0 publishes. Fails before any sink. |
| Length greater than **1000** | INVALID | 0 publishes. Fails before any sink. |
| N items, all body runs succeed | VALID | N publishes. `aggregatedResults` length N. |
| 10 items, 2 body runs throw | VALID | 8 publishes. `aggregatedResults` length 10, with 2 `error` entries. Successful messages stay published (no retry of those events). |
| N items, every body run throws | INVALID | 0 publishes. Retry is safe. |

Publish counts in this table assume the body ends with a sink. Without one, the same rules decide the job status, and nothing is published until a sink after For.

Iterations are **sequential**: one body in flight per For job. Wall time is about **N × body duration**.

## Timings (Test Step and ClickHouse)

For does not introduce a second clock. Test Step badges and ClickHouse timings read the same `JobResult.commandTimings` rows as every other command:

* Wrapper row: command type `execution_flow` for the For command itself
* Body rows: paths `.body.N` (N is the command index inside the body)
* Across iterations, body rows with the same path are **coalesced**: durations **sum**; start is the earliest; end is the latest

## Usage Examples

### Extract `events[]`, then For (JSONata + RabbitMQ sink)

Synthetic listing envelope:

```json theme={null}
{
  "events": [
    { "id": "evt-1", "home": "Alpha", "away": "Beta", "score": "1-0" },
    { "id": "evt-2", "home": "Gamma", "away": "Delta", "score": "0-0" }
  ],
  "bookmakerId": 42
}
```

Extract the array onto `data`, then iterate:

```json theme={null}
{
  "id": 1022,
  "type": "PARSE",
  "params": {
    "expression": "events",
    "timeout": 5000,
    "key": "data"
  }
}
```

```json theme={null}
{
  "id": 1101,
  "type": "EXECUTION_FLOW",
  "params": {
    "body": [
      {
        "id": 1022,
        "type": "PARSE",
        "params": {
          "expression": "{ 'eventId': id, 'label': home & ' vs ' & away, 'score': score }",
          "timeout": 5000,
          "key": "data"
        }
      },
      {
        "id": 1200,
        "type": "SINK",
        "params": {
          "exchange": "events",
          "routingKey": "data.processed",
          "data": {}
        }
      }
    ]
  }
}
```

Each sink message is one event. For output `data` is `{ "aggregatedResults": [ ... ] }` with one entry per event; failed events hold an `error` entry.

### Extract HTTP parallel `aggregatedResults`

After HTTP parallel 1002 or 1004, `data` looks like `{ "aggregatedResults": [ ... ] }`. Put the inner array onto `data` before For:

```json theme={null}
{
  "id": 1022,
  "type": "PARSE",
  "params": {
    "expression": "aggregatedResults",
    "timeout": 5000,
    "key": "data"
  }
}
```

Then the For command from the previous example.

## Common Use Cases

* **Per-event JSONata**: Write 1022 against one listing event instead of the whole envelope
* **One sink message per event**: Publish independent records without creating child Items
* **HTTP parallel follow-on**: Extract `aggregatedResults`, then For each response payload
* **Transform only**: Leave the sink out of the body and sink `aggregatedResults` once after For
* **Partial listings**: Keep the job VALID when some events fail, with each failure and its input in `aggregatedResults`

## Related Commands

* [If-Else](https://docs.bringits.com/stream/commands/execution-flow/if-else.md) - Conditional command lists (same `EXECUTION_FLOW` family, id 1100)
* [JSONata](https://docs.bringits.com/stream/commands/parse/jsonata.md) - Per-item transform (id 1022); also the extract onto `data` before For
* [Json Path](https://docs.bringits.com/stream/commands/parse/json-path.md) - Extract an array from a nested envelope
* [RabbitMQ Sink](https://docs.bringits.com/stream/commands/sink/rabbitmq-sink.md) - Typical sink at the end of the For body
* [HTTP Parallel Request](https://docs.bringits.com/stream/commands/http/http-parallel-request.md) - Output shape `{ data: { aggregatedResults } }` (id 1002)
* [HTTP Parallel Request - Got](https://docs.bringits.com/stream/commands/http/http-parallel-request-got.md) - Same output shape (id 1004)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.