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
Nonewhen not provided at runtime. - Validates route output types when enabled.
Configuration
- Drag the
ConditionalRoutercomponent onto the canvas from the Component Library. - Click on the component to open the configuration panel.
- 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,strorList[int]).output_name: The name of the output connection used to connect the router to other components.
- Define the Routes. Each route is a dictionary with four fields:
- 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
Nonewhen not provided. - Enable Unsafe to allow arbitrary code execution in Jinja2 templates (only use with trusted sources).
- Enable Validate Output Type to raise a
ValueErrorif 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, andoutput_nameas 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_typeand the actual output shape, or anoutput_namethat 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. |
Was this page helpful?