Subflows allow you to build modular and reusable workflow components. They work similarly to calling functions. A subflow execution is created when you call a flow from other flow.

How to declare a subflow

To call a flow from another flow, use the io.kestra.core.tasks.flows.Subflow task and in that task, specify the flowId and namespace of the subflow that you want to execute. Optionally, you can also specify custom input values, in the same way as you would pass arguments in a function call.

The optional properties wait and transmitFailed control the execution behavior. By default, if wait is not set or set to false, the parent flow continues execution without waiting for the subflow's completion. The transmitFailed property determines whether a failure in the subflow execution should cause the parent flow to fail.

Practical Example

Consider a subflow that encapsulates critical business logic. This subflow can be called from various flows, allowing for code reuse and isolated testing.

Here is a simple example of a subflow:

yaml
id: critical_service
namespace: dev

tasks:
  - id: return_data
    type: io.kestra.plugin.jdbc.duckdb.Query
    sql: |
      INSTALL httpfs;
      LOAD httpfs;
      SELECT sum(total) as total, avg(quantity) as avg_quantity
      FROM read_csv_auto('https://raw.githubusercontent.com/kestra-io/datasets/main/csv/orders.csv', header=True);
    store: true

In this example, return_data outputs uri of the query output. That URI is a reference to the Internal Storage location of the stored file. This output can be used in the parent flow to perform further processing.

yaml
id: parent_service
namespace: dev

tasks:
  - id: subflow_call
    type: io.kestra.core.tasks.flows.Subflow
    namespace: dev
    flowId: critical_service
    wait: true
    transmitFailed: true
    # output data from a specific subflow task called return_data
    outputs:
      some_output: "{{outputs.return_data.uri}}"

  - id: log_subflow_output
    type: io.kestra.plugin.scripts.shell.Commands
    runner: PROCESS
    commands:
      - cat "{{ outputs.subflow_call.outputs.some_output }}"

The outputs map task IDs to their outputs. In this case, we are accessing the outputs.some_output output of the subflow_call task.

Subflow properties

Below is a full list of all properties of the io.kestra.core.tasks.flows.Subflow task. Don't worry, you don't need to memorize them all, you can always open the task documentation to see the full list of Subflow task properties:

FieldDescription
flowIdThe subflow's identifier.
namespaceThe namespace where the subflow is located.
inheritLabelsDetermines if the subflow inherits labels from the parent (default: false).
inputsInputs passed to the subflow.
labelsLabels assigned to the subflow.
outputs (deprecated)Allows passing outputs from the subflow execution to the parent flow.
revisionThe subflow revision to execute (defaults to the latest).
waitIf true, parent flow waits for subflow completion (default: false).
transmitFailedIf true, parent flow fails on subflow failure (requires wait to be true).

Passing data between parent and child flows

Flows can emit outputs that can be accessed by the parent flow. Using the io.kestra.core.tasks.flows.Subflow task you can call any flow as a subflow and access its outputs in downstream tasks. For more details and examples, check the Outputs page.

Outputs from a subflow execution

Outputs include the execution ID, extracted outputs, and the final state (if wait is true).