Apex Switch On Sobject

Apex Switch on SObject

switch on over an SObject expression is the right tool for type-dispatch inside a heterogeneous collection — a generic trigger handler, a polymorphic processor, a classifier that runs different validation per object type. It buys two things over a chain of instanceof / getSObjectType().equals(...) checks: type-narrowed bindings inside each branch (no cast required) and a single explicit when else for the unhandled case.

What this skill is NOT. The simpler switch on Integer / String / enum form is plain Apex syntax — go directly to the Apex Developer Guide. Dynamic field access (Schema.getGlobalDescribe(), record.get(fieldName)) lives in apex/dynamic-apex. This skill is specifically about the SObject expression form and the branch-binding semantics.

Before Starting

• Confirm the dispatch is runtime — if you statically know the type at compile time, skip the switch and just write the typed code.
• Confirm whether when else is required: if the switch is non-exhaustive (you only handle some types), you almost always need when else because unmatched cases silently fall through to the end of the switch with no side-effect — that's the failure mode that hides bugs longest.
• Note that the binding form requires exactly one SObject type per when block. You cannot write when Account, Contact a { ... } and expect a typed a; that form is reserved for value-list matching on enums and primitives.

Core Concepts

The two switch-on-SObject forms

// Form 1 — bind a typed variable inside the branch (the whole point of this feature).
switch on record {
    when Account a {
        // 'a' is typed Account here. No cast, no Schema check.
        a.AccountNumber = generateAccountNumber();
    }
    when Contact c {
        c.LastName = c.LastName?.toUpperCase();
    }
    when null {
        // Reached only when 'record' itself is null — safe, no NullPointerException.
        return;
    }
    when else {
        // Anything else; the runtime type is something we didn't handle.
        // SILENTLY SKIPPING this branch is the #1 latent bug — declare it explicitly.
        System.debug('Unhandled SObjectType: ' + record.getSObjectType());
    }
}

// Form 2 — match by exact value (rare for SObjects; mostly for primitives).
switch on someInteger {
    when 1, 2, 3 { /* multi-value matching only works for primitives + enums */ }
    when else    { ... }
}

Three rules that bite people

1. No fall-through. Each when branch executes and the switch exits. There is no break keyword and no implicit fall-through to the next branch (unlike C / Java's switch).
2. when null matches a null expression. It does NOT match a record whose Id is null. It is reached only when the expression itself is null. This makes switch null-safe by design — no NullPointerException from the dispatch.
3. Type.forName(...) is NOT a substitute for SObjectType. Type.forName('Account') returns System.Type, which is not what switch on accepts in this form. To dispatch from a string name, look up the SObject prototype: Schema.getGlobalDescribe().get(name).newSObject() and switch on that.

Common Patterns

Pattern A — Polymorphic trigger handler

When to use. A single handler that runs across multiple SObject types (common in framework code, templates/apex/TriggerHandler.cls).

public class PolyHandler {
    public static void handle(List<SObject> records) {
        for (SObject record : records) {
            switch on record {
                when Account a   { handleAccount(a); }
                when Contact c   { handleContact(c); }
                when Lead l      { handleLead(l); }
                when else        {
                    // Programmer error — every type the framework registers must have a branch.
                    throw new HandlerException('Unhandled type: ' + record.getSObjectType());
                }
            }
        }
    }
}

Why not the alternative. A chain of if (record instanceof Account) { Account a = (Account) record; ... } is verbose and re-introduces casts that the binding form already handled.

Pattern B — Classifier with explicit unhandled-case

When to use. You handle some types and want all other types to fall through harmlessly with a logged warning.

public static String classify(SObject record) {
    switch on record {
        when Account a   { return a.Type;            }
        when Contact c   { return c.LeadSource;      }
        when null        { return null;              }
        when else        {
            // Crucial: without this branch, the method returns the default null
            // and the caller has no signal that 'record' was an unrecognized type.
            ApplicationLogger.warn('classify: unhandled ' + record.getSObjectType());
            return null;
        }
    }
}

Pattern C — Dispatch from a string type name

When to use. The caller has the type name as a string (config-driven dispatch, custom-metadata-driven router).

public static SObject createByName(String objectApiName) {
    Schema.SObjectType t = Schema.getGlobalDescribe().get(objectApiName);
    if (t == null) {
        throw new IllegalArgumentException('Unknown SObject: ' + objectApiName);
    }
    SObject prototype = t.newSObject();
    switch on prototype {
        when Account a   { return new Account(Name = 'Default Name');     }
        when Contact c   { return new Contact(LastName = 'Default Last'); }
        when else        {
            // The string named a real SObject, but this method only constructs a few.
            throw new IllegalArgumentException('Unsupported for default-create: ' + objectApiName);
        }
    }
}

Type.forName(objectApiName) does NOT work as the switch expression here — it returns System.Type, not an SObject prototype.

Decision Guidance

Recommended Workflow

1. Confirm runtime dispatch. If the type is known at compile time, write typed code; do not introduce a switch.
2. List every SObject type the dispatch can see. From the caller, the trigger registration, or the framework contract.
3. Choose when else semantics. Either (a) throw — programmer error, the dispatch should be exhaustive — or (b) log + return safely. Never omit when else on a non-exhaustive switch.
4. Place when null before when else if the expression can be null. The when null branch is the null-safety guarantee for the entire switch.
5. Verify in test. Write a test class that passes one record of every handled type plus one record of an unhandled type; assert the unhandled-case behavior matches step 3.

Review Checklist

• Switch has either when else or every concrete SObject type the caller can pass.
• when null branch present if the expression can be null.
• No when else block silently returns / does nothing without a comment justifying it.
• No use of Type.forName(...) as the switch expression.
• Test class covers one record of every handled type + one unhandled type.
• Each branch's bound variable is used (or removed); unused-binding is a smell that the branch could be just when Account without binding.

Salesforce-Specific Gotchas

1. Silent skip without when else. A non-exhaustive switch on an unhandled type does nothing — no exception, no warning. Always declare when else. (See references/gotchas.md § 1.)
2. Type.forName('Account') does not produce a switch-able expression. It returns System.Type. You need Schema.getGlobalDescribe().get('Account').newSObject() to get an SObject prototype. (See references/gotchas.md § 2.)
3. Multi-type-per-when is not supported. when Account a, Contact c { ... } does not compile. (See references/gotchas.md § 3.)
4. when null matches the expression being null, not an SObject with Id = null. Don't use it for "new record" detection. (See references/gotchas.md § 4.)
5. Managed-package custom SObjects need the namespace. when my_pkg__Custom_Object__c c { ... } — the namespace is part of the type identity. (See references/gotchas.md § 5.)

Output Artifacts

Related Skills

• apex/dynamic-apex — Schema.getGlobalDescribe / dynamic field access; pair with this skill when dispatching from a string API name
• apex/trigger-framework — when this dispatch goes inside a generic trigger handler; templates/apex/TriggerHandler.cls is the canonical base
• apex/apex-mocking-and-stubs — for the test class that exercises every branch