Switch Node Guide

Route data to different paths based on values, patterns, ranges, and conditions

Using the Switch Node

The Switch Node lets you route data to different paths based on conditions. Think of it like an if/else statement, but more flexible.

Status: Production-Ready ✅ Version: 1.0 Last Updated: November 2025

How It Works

The Switch Node evaluates your data against rules and outputs to a matching port:

Input: { status: "premium", amount: 500 }
         ↓
    ┌────────────────┐
    │  Switch Node   │
    │  Check: status │
    └────────────────┘
         ↓
    ┌─────────────────────┐
    │ "premium" → premium_path
    │ "standard" → standard_path
    │ else → default_path
    └─────────────────────┘
         ↓
    Output: premium_path

5 Routing Modes

Mode 1: VALUE — Match Exact Values

Use when: Checking if something equals a specific value.

mode: "value"
fieldToCheck: "status"
routingRules:
  "premium": premiumPath
  "standard": standardPath
  "basic": basicPath
defaultOutput: otherPath

Example:

Input: { status: "premium" }
         ↓
Output to: premiumPath

Ports created:

  • premiumPath, standardPath, basicPath, otherPath (default), error

Mode 2: PATTERN — Match Text Patterns

Use when: Matching email domains, file extensions, or prefixes.

mode: "pattern"
fieldToCheck: "email"
routingRules:
  "*@example.com": internalQueue
  "*@gmail.com": externalQueue
  "admin-*": adminQueue
defaultOutput: otherQueue

Example:

Input: { email: "alice@example.com" }
         ↓
Output to: internalQueue

Supported patterns:

  • *@example.com — Ends with
  • admin-* — Starts with
  • *dev* — Contains

Mode 3: RANGE — Match Number Ranges

Use when: Routing by age, score, amount, etc.

mode: "range"
fieldToCheck: "score"
routingRules:
  low:
    min: 0
    max: 50
  medium:
    min: 51
    max: 80
  high:
    min: 81
    max: 100
defaultOutput: invalid

Example:

Input: { score: 75 }
         ↓
Output to: medium

Tip: Ranges are inclusive. 50 goes to low, not medium.

Mode 4: TYPE — Match Data Type

Use when: Routing based on what type of data you have.

mode: "type"
fieldToCheck: "value"
routingRules:
  "string": textProcessor
  "number": mathProcessor
  "array": listProcessor
  "object": objectProcessor
defaultOutput: unknownType

Example:

Input: { value: "hello" }
         ↓
Output to: textProcessor

Supported types:

  • string, number, boolean, array, object, null

Mode 5: EXPRESSION — Custom Logic

Use when: You need complex conditions.

mode: "expression"
routingRules:
  autoApprove: "{{ $input.amount < 100 }}"
  review: "{{ $input.amount >= 100 && $input.amount < 1000 }}"
  escalate: "{{ $input.amount >= 1000 }}"
defaultOutput: invalid

Example:

Input: { amount: 250 }
         ↓
Check: 250 < 100? NO
Check: 250 >= 100 && 250 < 1000? YES
         ↓
Output to: review

Complete Examples

Example 1: User Role Routing

Switch Node:
  mode: "value"
  fieldToCheck: "role"
  routingRules:
    "admin": adminDashboard
    "manager": managerDashboard
    "user": userDashboard
    "guest": loginRequired
  defaultOutput: loginRequired

Outputs: adminDashboard, managerDashboard, userDashboard, loginRequired, error

Workflow:

User login
    ↓
Get user profile
    ↓
┌─────────────┐
│ Switch by   │
│ role        │
└──────┬──────┘
   ↙  ↓  ↘
admin  manager  user

Example 2: Order Amount Routing

Switch Node:
  mode: "range"
  fieldToCheck: "orderTotal"
  routingRules:
    small:
      min: 0
      max: 50
    medium:
      min: 51
      max: 200
    large:
      min: 201
  defaultOutput: invalid

Outputs: small, medium, large, invalid, error

Real-world: Route orders to different fulfillment warehouses based on size.

Example 3: Email Routing

Switch Node:
  mode: "pattern"
  fieldToCheck: "emailDomain"
  routingRules:
    "*@company.com": internalEmail
    "*@partner.com": partnerEmail
    "support@*": supportEmail
  defaultOutput: externalEmail

Outputs: internalEmail, partnerEmail, supportEmail, externalEmail, error

Example 4: Approval Decision

Switch Node:
  mode: "expression"
  routingRules:
    autoApprove: "{{ $input.amount < 500 && $input.verified }}"
    managerReview: "{{ $input.amount >= 500 && $input.amount < 5000 }}"
    ceoApproval: "{{ $input.amount >= 5000 }}"
  defaultOutput: rejected

Outputs: autoApprove, managerReview, ceoApproval, rejected, error

Standard Output Ports

Every switch node has two extra ports:

  • default — Used when no rules match (name is configurable)
  • error — Routes here if something goes wrong

Example ports:

- rule1Output
- rule2Output
- rule3Output
- default (fallback)
- error (if something breaks)

Configuration Tips

Tip 1: Order Matters for Ranges

More specific ranges first:

❌ Wrong:

low:
  min: 0
  max: 100  # Too broad!
high:
  min: 51
  max: 100  # Never reached

✅ Correct:

high:
  min: 51
  max: 100  # Specific
low:
  min: 0
  max: 50   # Then less specific

Tip 2: Use Descriptive Names

❌ Wrong:

routingRules:
  "a": path1
  "b": path2

✅ Correct:

routingRules:
  "premium": premiumUserPath
  "standard": standardUserPath

Tip 3: Always Set Default

routingRules:
  "option1": path1
  "option2": path2
defaultOutput: unknownPath  # Catches everything else

Never forget the default! Otherwise unmatched data creates errors.

Tip 4: Test Expression Syntax

When using expressions, test them first in a separate node:

1. Create a debug node
2. Test: {{ $input.amount < 500 }}
3. Verify it returns true/false
4. Then use in Switch node

Common Mistakes & Solutions

Mistake 1: Forgetting Default

❌ Wrong:

mode: "value"
routingRules:
  "option1": path1
  "option2": path2
# What happens if value is "option3"?

✅ Correct:

mode: "value"
routingRules:
  "option1": path1
  "option2": path2
defaultOutput: unknownPath

Mistake 2: Wrong Field Name

❌ Wrong:

fieldToCheck: "user_status"  # Field is actually "userStatus"

✅ Correct:

fieldToCheck: "userStatus"  # Match actual field name

Use Data Mapper to see available fields!

Mistake 3: Type Mismatch

❌ Wrong:

mode: "range"
routingRules:
  low:
    min: "0"      # String, not number!
    max: "100"

✅ Correct:

mode: "range"
routingRules:
  low:
    min: 0        # Numbers, not strings
    max: 100

Best Practices

  • ✅ Use clear port names — "premiumPath" not "path1"
  • ✅ Always have a default — Handle unexpected values
  • ✅ Test with sample data — Verify routing works
  • ✅ Use expressions for complex logic — More flexible than ranges
  • ✅ Handle the error port — Log unexpected errors
  • ❌ Don't rely on type checking — It's fragile
  • ❌ Don't hardcode values — Use expressions for dynamic routing
  • ❌ Don't forget edge cases — Null, empty strings, missing fields

Port Naming Rules

DeepChain automatically converts names to readable format:

Input Name Display Name
premiumPath "Premium Path"
standard_path "Standard Path"
basicService "Basic Service"
admin-only "Admin Only"

Keep names:

  • Concise (not too long)
  • Descriptive (says what it does)
  • Consistent (camelCase or snake_case, not mixed)

Quick Reference

When to Use Each Mode

Mode Use Case Example
Value Exact match status = "approved"
Pattern Text matching email ends with "@company.com"
Range Number ranges score between 80-100
Type Data type is this a string or number?
Expression Complex logic amount < 100 AND verified

Next Steps

  • Start simple — Use "value" mode for your first switch
  • Test your routing — Run with sample data
  • Add error handling — Connect error port to logging
  • Graduate to expressions — Use for complex logic
  • Build real workflows — Combine with approvals, notifications

Related: