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.

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. For example, connect router.enough_streams to one component and router.insufficient_streams to another.

Source Code

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

Usage Examples

Basic Configuration

  ConditionalRouter:
    type: components.routers.conditional_router.ConditionalRouter
    init_parameters: {}

Connections

components:
  ConditionalRouter:
    type: components.routers.conditional_router.ConditionalRouter
    init_parameters:

Here is a Python example that shows how to configure routes and connect the router:

from typing import List
from haystack import Pipeline
from haystack.dataclasses import ByteStream
from haystack.components.routers import ConditionalRouter

routes = [
    {
        "condition": "{{streams|length > 2}}",
        "output": "{{streams}}",
        "output_name": "enough_streams",
        "output_type": List[ByteStream],
    },
    {
        "condition": "{{streams|length <= 2}}",
        "output": "{{streams}}",
        "output_name": "insufficient_streams",
        "output_type": List[ByteStream],
    },
]

pipe = Pipeline()
pipe.add_component("router", router)
...
pipe.connect("router.enough_streams", "some_component_a.streams")
pipe.connect("router.insufficient_streams", "some_component_b.streams_or_some_other_input")
...

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.