MetadataRouter

Use MetadataRouter to route documents or byte streams to different pipeline branches based on their metadata fields. Unmatched items are sent to a dedicated unmatched output.

Key Features

• Routes documents or byte streams based on metadata filter conditions
• Supports Haystack metadata filtering syntax for conditions (field, operator, value)
• Creates one named output per rule for direct downstream connections
• Routes non-matching items to a dedicated unmatched output
• Handles both Document and ByteStream objects

Configuration

1. Drag the MetadataRouter component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. On the General tab:
   1. Set rules to a dictionary mapping output connection names to Haystack filtering expressions. Each key becomes an output connection name, and the value is a filter condition.
4. Go to the Advanced tab to configure output_type (choose documents or byte_streams).

Connections

MetadataRouter accepts a list of documents or byte streams as input. It evaluates each item against the defined rules and sends matching items to the corresponding named output. Items that don't match any rule go to unmatched. Connect each named output to the appropriate downstream component.

Usage Example

components:
  MetadataRouter:
    type: components.routers.metadata_router.MetadataRouter
    init_parameters:
      output_type: documents  # or byte_streams
      rules:
        edge_1:
          operator: AND
          conditions:
          - field: meta.created_at
            operator: ">="
            value: "2023-01-01"
          - field: meta.created_at
            operator: "<"
            value: "2023-04-01"

Parameters

Inputs

Parameter	Type	Default	Description
documents	List[Document]		A list of documents to route.
byte_streams	List[ByteStream]		A list of byte streams to route.

Outputs

The component creates one output per key in rules, plus an unmatched output for items that don't match any rule.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
rules	Dict[str, Dict]		A dictionary mapping output connection names to Haystack filtering expressions. Keys become output connection names. Values are filter condition dictionaries. For example: {"edge_1": {"operator": "AND", "conditions": [{"field": "meta.created_at", "operator": ">=", "value": "2023-01-01"}, {"field": "meta.created_at", "operator": "<", "value": "2023-04-01"}]}}.
output_type	Optional[str]	documents	The type of objects to route. Use documents or byte_streams. Defaults to documents for backward compatibility.

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
documents	List[Document]		A list of documents to route.
byte_streams	List[ByteStream]		A list of byte streams to route.