ForEach

type: "io.kestra.plugin.core.flow.ForEach"

Execute a group of tasks for each value in the list.

You can control how many task groups are executed concurrently by setting the concurrencyLimit property.

• If you set the concurrencyLimit property to 0, Kestra will execute all task groups concurrently for all values.
• If you set the concurrencyLimit property to 1, Kestra will execute each task group one after the other starting with the task group for the first value in the list.

Regardless of the concurrencyLimit property, the tasks will run one after the other — to run those in parallel, wrap them in a Parallel task as shown in the last example below (see the flow parallel_tasks_example).

The values should be defined as a JSON string or an array, e.g. a list of string values ["value1", "value2"] or a list of key-value pairs [{"key": "value1"}, {"key": "value2"}].

You can access the current iteration value using the variable {{ taskrun.value }} or {{ parent.taskrun.value }} if you are in a nested child task.

If you need to execute more than 2-5 tasks for each value, we recommend triggering a subflow for each value for better performance and modularity. Check the flow best practices documentation for more details.

Examples

The {{ taskrun.value }} from the for_each task is available only to direct child tasks such as the before_if and the if tasks. To access the taskrun value of the parent task in a nested child task such as the after_if task, use {{ parent.taskrun.value }}.

id: for_loop_example
namespace: company.team

tasks:
  - id: for_each
    type: io.kestra.plugin.core.flow.ForEach
    values: ["value 1", "value 2", "value 3"]
    tasks:
      - id: before_if
        type: io.kestra.plugin.core.debug.Return
        format: "Before if {{ taskrun.value }}"
      - id: if
        type: io.kestra.plugin.core.flow.If
        condition: '{{ taskrun.value == "value 2" }}'
        then:
          - id: after_if
            type: io.kestra.plugin.core.debug.Return
            format: "After if {{ parent.taskrun.value }}"

This flow uses YAML-style array for values. The task for_each iterates over a list of values and executes the return child task for each value. The concurrencyLimit property is set to 2, so the return task will run concurrently for the first two values in the list at first. The return task will run for the next two values only after the task runs for the first two values have completed.

id: for_each_value
namespace: company.team

tasks:
  - id: for_each
    type: io.kestra.plugin.core.flow.ForEach
    values:
      - value 1
      - value 2
      - value 3
      - value 4
    concurrencyLimit: 2
    tasks:
      - id: return
        type: io.kestra.plugin.core.debug.Return
        format: "{{ task.id }} with value {{ taskrun.value }}"

This example shows how to run tasks in parallel for each value in the list. All child tasks of the parallel task will run in parallel. However, due to the concurrencyLimit property set to 2, only two parallel task groups will run at any given time.

id: parallel_tasks_example
namespace: company.team

tasks:
  - id: for_each
    type: io.kestra.plugin.core.flow.ForEach
    values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    concurrencyLimit: 2
    tasks:
      - id: parallel
        type: io.kestra.plugin.core.flow.Parallel
        tasks:
        - id: log
          type: io.kestra.plugin.core.log.Log
          message: Processing {{ parent.taskrun.value }}
        - id: shell
          type: io.kestra.plugin.scripts.shell.Commands
          commands:
            - sleep {{ parent.taskrun.value }}

Properties

concurrencyLimit

• Type: integer
• Dynamic: ❌
• Required: ✔️
• Default: 1
• Minimum: >= 0

The number of concurrent task groups for each value in the values array.

If you set the concurrencyLimit property to 0, Kestra will execute all task groups concurrently for all values (zero limits!).

If you set the concurrencyLimit property to 1, Kestra will execute each task group one after the other starting with the first value in the list (limit concurrency to one task group that can be actively running at any time).

values

• Type:
  • string
  • array
• Dynamic: ✔️
• Required: ✔️

The list of values for which Kestra will execute a group of tasks.

The values can be passed as a string, a list of strings, or a list of objects.

errors

• Type: array
• SubType: Task
• Dynamic: ❌
• Required: ❌

List of tasks to run if any tasks failed on this FlowableTask.

tasks

• Type: array
• SubType: Task
• Dynamic: ❌
• Required: ❌