ConditionalRouter

Route data to different pipeline branches based on conditions you define using Jinja2 expressions.

Key Features

• Routes data to different outputs based on configurable Jinja2 conditions.
• Supports multiple routes, each with its own condition, output, output type, and output name.
• Supports custom Jinja2 filters for advanced condition logic.
• Supports optional variables that fall back to None when not provided at runtime.
• Validates route output types when enabled.

Configuration

1. Drag the ConditionalRouter component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Define the Routes. Each route is a dictionary with four fields:
     • condition: A Jinja2 expression that determines if the route is selected.
     • output: A Jinja2 expression defining the value to pass to the output.
     • output_type: The data type of the output (for example, str or List[int]).
     • output_name: The name of the output connection used to connect the router to other components.
4. Go to the Advanced tab to configure optional settings:
   • Set Custom Filters to add custom Jinja2 filters for use in condition expressions.
   • Set Optional Variables to list variables that should default to None when not provided.
   • Enable Unsafe to allow arbitrary code execution in Jinja2 templates (only use with trusted sources).
   • Enable Validate Output Type to raise a ValueError if a route output doesn't match its declared type.

Redesigned Route Editor

On organizations with the redesigned route editor enabled, the Routes field on the General tab opens a dedicated editor instead of a raw list field:

• Each route appears as its own block labeled If, Else if, or Else. The first block is always If; you can add as many Else if blocks as you need, and an Else block is optional and explicit.
• You write each route's condition, output, output_type, and output_name as YAML directly inside its block.
• Drag a route block by its handle to reorder routes. Route order still determines evaluation order at runtime.
• Each block shows a Valid or Invalid badge. A route is marked invalid if it has malformed Jinja2 delimiters, a mismatch between the declared output_type and the actual output shape, or an output_name that duplicates another route's.
• If you rename or remove a route's output_name, any canvas connections from that route are automatically re-pointed or removed so your pipeline doesn't end up with dangling connections.

On the canvas, an expanded ConditionalRouter node card shows a condition row for each route, and each route has its own connectable output handle instead of a single shared connection point.

To try this feature, ask deepset to enable it for your organization.

Connections

ConditionalRouter accepts any variables used in the route conditions as inputs. Connect upstream component outputs to the corresponding input names. Each route produces a named output you can connect to a different downstream component.

Source Code

To check this component's source code, open conditional_router.py in the Haystack repository.

Usage Examples

Basic Configuration

  ConditionalRouter:
    type: haystack.components.routers.conditional_router.ConditionalRouter
    init_parameters:
      routes:
      - condition: "{{ '?' in query }}"
        output: "{{ query }}"
        output_name: question
        output_type: str
      - condition: "{{ '?' not in query }}"
        output: "{{ query }}"
        output_name: statement
        output_type: str

Using the Component in a Pipeline

This example routes a query based on whether it contains a question mark. Questions and statements go to different LLM components with different prompts, then BranchJoiner consolidates the replies into a single output.

# haystack-pipeline
components:
  ConditionalRouter:
    type: haystack.components.routers.conditional_router.ConditionalRouter
    init_parameters:
      routes:
      - condition: "{{ '?' in query }}"
        output: "{{ query }}"
        output_name: question
        output_type: str
      - condition: "{{ '?' not in query }}"
        output: "{{ query }}"
        output_name: statement
        output_type: str
  QuestionLLM:
    type: haystack.components.generators.chat.llm.LLM
    init_parameters:
      chat_generator:
        init_parameters:
          model: gpt-5.4
        type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
      system_prompt: ''
      user_prompt: |-
        {% message role="user" %}
        Provide a detailed answer to this question: {{ query }}
        {% endmessage %}
      required_variables:
      - query
      streaming_callback:
  StatementLLM:
    type: haystack.components.generators.chat.llm.LLM
    init_parameters:
      chat_generator:
        init_parameters:
          model: gpt-5.4
        type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
      system_prompt: ''
      user_prompt: |-
        {% message role="user" %}
        Acknowledge and expand on this statement: {{ query }}
        {% endmessage %}
      required_variables:
      - query
      streaming_callback:
  BranchJoiner:
    type: haystack.components.joiners.branch.BranchJoiner
    init_parameters:
      type_: haystack.dataclasses.chat_message.ChatMessage

connections:
- sender: ConditionalRouter.question
  receiver: QuestionLLM.query
- sender: ConditionalRouter.statement
  receiver: StatementLLM.query
- sender: QuestionLLM.last_message
  receiver: BranchJoiner.value
- sender: StatementLLM.last_message
  receiver: BranchJoiner.value

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - ConditionalRouter.query

outputs:
  replies: BranchJoiner.value

Parameters

Inputs

Parameter	Type	Description
kwargs	Any	All variables used in the condition expressions in the routes. When used in a pipeline, these variables are passed from the previous component's output.

Outputs

Parameter	Type	Description
(dynamic)	Declared output_type	Each route produces a named output corresponding to its output_name.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
routes	List[Route]		A list of dictionaries, each defining a route. Each route has four fields: condition (Jinja2 expression), output (Jinja2 expression), output_type (data type), and output_name (output connection name).
custom_filters	Optional[Dict[str, Callable]]	None	A dictionary of custom Jinja2 filters for use in condition expressions. Keys are filter names, values are callables.
unsafe	bool	False	Enable execution of arbitrary code in Jinja2 templates. Only use this if you trust the source of the template, as it can lead to remote code execution.
validate_output_type	bool	False	Enable validation of route outputs. If a route output doesn't match the declared type, a ValueError is raised at runtime.
optional_variables	Optional[List[str]]	None	A list of variable names that are optional in route conditions and outputs. If not provided at runtime, these variables are set to None.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
kwargs	Any		All variables used in the condition expressions in the routes. When used in a pipeline, these variables are passed from the previous component's output.