--- title: "Use the SWITCH Function to Return Values Based on Conditions" slug: "switch-function" description: "Learn to use the SWITCH function to compare expressions against conditions and return the first match or a default result in Pigment." updated: 2025-05-30T09:38:44Z published: 2025-08-22T10:57:28Z --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # SWITCH function ## Description Compares one expression or block against a list of conditions and results, and returns the result of the first matching condition. If there is no match, returns an optional default result or blank if there is no default. ## Syntax `SWITCH(Expression, Value1, Result1 [, ValueN, ResultN] [, Default])` | Argument | Type | Dimensions | Description | | --- | --- | --- | --- | | *Expression* | Any | Any | Can be a List Property, a Metric, a List or a Formula returning a result. Each value of the *Expression* will be compared to the values provided in the Switch. | | *Value1* | Any | No Dimension | At least one pair of {value, result} is required. Must be a scalar value and of the same data type as *Expression*. A scalar in this context is a singular (not dimensioned) value. | | *Result1* | Any | Any | The result when a value of *Expression* matches *Value1*. | | *ValueN* (optional) | Same as *Value1* | No Dimension | Same as *Value1*: you can provide any number of pairs, so you can have `Value2, Result2, Value3, Result3`... | | *ResultN* (required for each *ValueN*) | Same as *Result1* | Any | Same as Result1. | | *Default* (optional) | Same as *Result1* | Subset of *Result1* | Optional argument that defines the output when there is no match for any *Value*, **including** blank values from *Expression*. | ## Return type Same data type as the Result values. ## Example Note that to improve readability, especially with multiple {value, result} pairs, it is recommended to put each one on a separate line. | **Case** | **Return Type** | **Result** | | --- | --- | --- | | `SWITCH('Status', 0, "Inactive", 1, "Active")` | `Text` | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/1ceb41fa-1e17-40c0-82fb-246de77bb62c.png) BR has blank and non-matching values, so the results are blank (no default value) (click to enlarge) | | `SWITCH('Status', 0, "Inactive", 1, "Active", "Decommissioned")` | `Text` | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/9d58030a-d3c4-41fd-8851-442d977d6807.png) BR has blank and non-matching values, so the result has the default value (click to enlarge) | | `SWITCH('Code', "A", 1, "B", 2, 'Code Default')` | `Number` | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/f5947ccc-bbd5-4393-8b8a-f974cb617d92.png) Similar example with a Metric used as Default (click to enlarge) | | `SWITCH(Region, Region."EU", "Europe", Region."NA", "North America", Region."LATAM", "Latin America")` | `Text` | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/bac3e0fc-52aa-4fda-b0c8-686f44d3cf76.png) Switch on a Dimension (click to enlarge) | ## Tips When using the Switch function with Dimension items, a common mistake is to specify values as strings instead of “references”. The main risk with strings is that it’s not future proof, e.g. renaming the value in the source Dimension could silently break some Switch cases: | ❌ Not recommended | ✅ D**o this instead** | | --- | --- | | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/89c7a0e4-4923-4d5c-975f-1022a51be8b4.png) click to enlarge If you rename “NA” to “North America” in the Region dimension, the Switch will still have “NA” and won’t match that value anymore. | ![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/cd2ad202-9d62-42ed-be7c-268a2d84b17d.png) click to enlarge Notice how `Region.Name` became just `Region`. Now if we rename any value in the Region dimension, it will update the value in the Switch automatically as it’s referencing the dimension item, not the literal string. | > [!NOTE] > Note that this is true not only for the Switch, and is a best practice to follow as much as possible. **Excel equivalent**: [SWITCH(expression, value1, result1, [default or value2, result2],…[default or value3, result3])](https://support.microsoft.com/en-us/office/switch-function-47ab33c0-28ce-4530-8a45-d532ec4aa25e) **See also**: [IF](/v1/docs/if-function) > [!TIP] > More of a hands-on learner? > > Talk to your Customer Success Manager about downloading the Functions and Modifiers in Pigment Application into your workspace. It includes examples of every formula and modifier in Pigment!