<!-- BusyBot node reference — https://busybot.net/tools/switch/ -->

> Node: Switch (`switch`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Switch

> Route to multiple outputs by value

## Overview

Routes workflow items to multiple output branches based on configurable rules or expressions. Supports complex business logic with many possible paths.

**Category:** Core Nodes  
**Tool Name:** `switch`  
**Version:** 1

**Appearance:** Icon: `switch` | Color: `#f97316`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output 0`, `Output 1`, `Output 2`, `Output 3`, `Output 4`, `Output 5`, `Output 6`, `Output 7`, `Output 8`, `Output 9`, `Fallback` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | Yes | `rules` | Rules Mode: Define matching conditions for each output. Expression Mode: Use an expression that returns an output index (0-9). |
| | | | | Options: `rules`, `expression` |
| Output Index Expression | `string` | Yes | `{{ $json.outputIndex }}` | Expression that evaluates to an output index (0-9). Example: {{ $json.tier === 'gold' ? 0 : ($json.tier === 'silver' ? 1 : 2) }} _(shown when Mode is `expression`)_ |
| Routing Rules | `fixedCollection` | No | `{}` | Define conditions for routing items to different outputs. _(shown when Mode is `rules`)_ |
| — Output Index | `number` | No | `0` | Which output (0-9) to route matching items to. |
| — Output Name | `string` | No | — | Optional friendly name for this output (for documentation purposes). |
| — Combine Conditions With | `options` | No | `and` | How to combine multiple conditions for this rule. |
| | | | | Options: `and` (all conditions must match), `or` (any condition may match) |
| — Conditions | `fixedCollection` | No | `{}` | The conditions this rule evaluates. |
| — — Field | `string` | No | `{{ $json.field }}` | Field to evaluate. Use expression syntax: {{ $json.fieldName }} or {{ $json.nested.field }} |
| — — Data Type | `options` | No | `string` | The data type of the field being compared. |
| | | | | Options: `string`, `number`, `boolean`, `dateTime`, `array`, `object` |
| — — Operation (`operation`) | `options` | No | `equals` | String comparison operation to perform. _(shown when Data Type is `string`)_ |
| | | | | Options: `equals`, `notEquals`, `contains`, `notContains`, `startsWith`, `endsWith`, `matchesRegex`, `isEmpty`, `isNotEmpty`, `exists`, `notExists` |
| — — Operation (`operation`) | `options` | No | `equals` | Number comparison operation to perform. _(shown when Data Type is `number`)_ |
| | | | | Options: `equals`, `notEquals`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `exists`, `notExists` |
| — — Operation (`operation`) | `options` | No | `isTrue` | Boolean comparison operation to perform. _(shown when Data Type is `boolean`)_ |
| | | | | Options: `isTrue`, `isFalse`, `equals`, `exists`, `notExists` |
| — — Operation (`operation`) | `options` | No | `equals` | Date/Time comparison operation to perform. _(shown when Data Type is `dateTime`)_ |
| | | | | Options: `equals`, `notEquals`, `greaterThan` (after), `greaterThanOrEqual` (after or equal), `lessThan` (before), `lessThanOrEqual` (before or equal), `exists`, `notExists` |
| — — Operation (`operation`) | `options` | No | `arrayContains` | Array comparison operation to perform. _(shown when Data Type is `array`)_ |
| | | | | Options: `arrayContains`, `arrayNotContains`, `arrayLengthEquals`, `arrayLengthGreaterThan`, `arrayLengthLessThan`, `isEmpty`, `isNotEmpty`, `exists`, `notExists` |
| — — Operation (`operation`) | `options` | No | `hasKey` | Object comparison operation to perform. _(shown when Data Type is `object`)_ |
| | | | | Options: `hasKey`, `notHasKey`, `isEmpty`, `isNotEmpty`, `exists`, `notExists` |
| — — Value | `string` | No | — | Value to compare against. Supports expressions: {{ $json.otherField }} _(hidden when Operation is `exists`, `notExists`, `isEmpty`, `isNotEmpty`, `isTrue`, `isFalse`, `matchesRegex`)_ |
| — — Regex Pattern | `string` | No | — | Regular expression pattern to match against. _(shown when Operation is `matchesRegex`)_ |
| Fallback Behavior | `options` | No | `output` | What to do with items that don't match any rule or have an invalid expression result. |
| | | | | Options: `output` (send to the Fallback output), `drop` (discard the item entirely), `error` (create an error item) |
| Include Match Info | `boolean` | No | `false` | Add _switchMatch metadata to output items showing which rule/output they matched. |
| Max Concurrency | `number` | No | `50` | Maximum items to process concurrently. |

## Output Data

Each input item leaves through exactly one output. The item JSON passes through unchanged and binary data is forwarded; the node only adds a property when Include Match Info is on.

- **Rules Mode** — rules are evaluated in the order you list them and the first match wins, so put the most specific rule first. The item goes to that rule's Output Index. A rule with no conditions is skipped.
- **Expression Mode** — the item goes to the output whose index the expression returns. A result that is not a whole number between 0 and 9 counts as no match.
- **No match** — Fallback Behavior decides. `output` sends the item to the `Fallback` output; `drop` discards it, so it leaves the workflow and reaches no output at all; `error` turns it into an item error.

With Include Match Info on, each output item carries:

```json
{
  "_switchMatch": {
    "mode": "rules",
    "outputIndex": 0,
    "matchReason": "Gold Tier",
    "matchedAt": 1765432100000,
    "ruleName": "Gold Tier"
  }
}
```

- `matchReason` is the matching rule's Output Name when it has one, otherwise `rule_{position}_output_{index}`. In Expression Mode it reads `expression_result:{index}`, or `expression_invalid` when the expression did not produce a usable index. An item that fell through to the fallback output reads `fallback`.
- `ruleName` is added in Rules Mode only, and is `null` when the matching rule has no Output Name.
- `Fallback` is also the error output. With error handling set to **continue** (the default), an item that fails is routed to `Fallback` carrying an `_error` object, so check for it before treating that branch as unmatched traffic.

Reference the metadata downstream by expression, e.g. `{{ $json._switchMatch.outputIndex }}`.

## Usage Examples

- switch based on status field
- route orders to different handlers by type
- dispatch to team based on priority
- categorize items into buckets
- direct traffic based on region

## Example Configuration

Route customers to one branch per subscription tier, with everything else going to the fallback output:

```json
{
  "type": "switch",
  "parameters": {
    "mode": "rules",
    "fallbackBehavior": "output",
    "includeMatchInfo": true,
    "rules": {
      "rule": [
        {
          "outputIndex": 0,
          "outputName": "Gold Tier",
          "combineOperation": "and",
          "conditions": {
            "condition": [
              {
                "field": "{{ $json.subscription.tier }}",
                "dataType": "string",
                "operation": "equals",
                "value": "gold"
              }
            ]
          }
        },
        {
          "outputIndex": 1,
          "outputName": "Silver Tier",
          "combineOperation": "and",
          "conditions": {
            "condition": [
              {
                "field": "{{ $json.subscription.tier }}",
                "dataType": "string",
                "operation": "equals",
                "value": "silver"
              }
            ]
          }
        }
      ]
    }
  }
}
```

Send high-value or long-standing customers down a single VIP branch — any one condition is enough:

```json
{
  "type": "switch",
  "parameters": {
    "mode": "rules",
    "fallbackBehavior": "output",
    "rules": {
      "rule": [
        {
          "outputIndex": 0,
          "outputName": "VIP Processing",
          "combineOperation": "or",
          "conditions": {
            "condition": [
              {
                "field": "{{ $json.vipStatus }}",
                "dataType": "boolean",
                "operation": "isTrue"
              },
              {
                "field": "{{ $json.purchaseAmount }}",
                "dataType": "number",
                "operation": "greaterThanOrEqual",
                "value": "1000"
              }
            ]
          }
        }
      ]
    }
  }
}
```

Pick the output branch with an expression instead of rules:

```json
{
  "type": "switch",
  "parameters": {
    "mode": "expression",
    "outputExpression": "{{ $json.priority === 'high' ? 0 : ($json.priority === 'medium' ? 1 : 2) }}",
    "fallbackBehavior": "output",
    "includeMatchInfo": true
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Evaluates input data against multiple routing rules and directs items to the first matching output branch. Use when items need to be categorized into 3+ distinct paths based on field values or conditions. Produces items on the output branch whose rule matched first, with unmatched items going to a fallback output.

### Key Usage Notes

- **Rules vs Expression Mode:** Use rules mode for simple condition-based routing. Use expression mode for complex calculated routing or when you need dynamic output selection.
- **Output Indexing:** Outputs are numbered 0-9. Ensure your rules or expressions return values within this range.
- **Fallback Behavior:** Always consider what should happen to items that don't match any conditions. Use "drop" carefully as items will be lost from the workflow.
- **Match Info:** Enable `includeMatchInfo` when debugging or when downstream nodes need to know which rule was matched.