Customize Your Tableau Data Story: Context Variables
Important changes for Tableau Data Stories
Tableau Data Stories will be retired in Tableau Desktop, Tableau Cloud, and Tableau Server in January of 2025 (2025.1). With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau Pulse powered by Tableau AI is Reimagining the Data Experience(Link opens in a new window).
Context variables are functions that can be referenced by other functions. In other words, you can use context variables to nest functions within other functions.
After you define your context variable, it appears as a function that you can use when adding new functions to your Tableau Data Story.
Note: You can have multiple context variables set for each custom sentence, but you must define each context variable separately for each piece of custom content.
Set a context variable
- In your Data Story, click Edit to open the Edit dialog box.
- Click Add Custom Item.
- Click the menu in the right side of your custom content box and select Set context.
- Click Add context.
- Name the context variable and click Set Function.
- Define your custom function and choose a dimension.
- Click Add to Section.
- Click back into the sentence where you set your context variable.
- Follow the steps to Add functions.
Now, your context variable is listed as an option in the Dimension Value drop-down list when adding your function.
Let’s say that you want to refer to two or more measures in one analytical sentence in your Data Story. Without a context variable, we can write a sentence for only one measure at a time. But if we use a context variable, we can reference more than one measure in one sentence.
To reference two or more measures with a context variable, your Data Story must have:
- 1 dimension
- 2 or more measures
- In your Data Story, click Edit to open the Edit dialog box.
- Click Add Custom Item.
- Click the menu in the right side of your custom content box and select Set context.
- Click Add context.
- Name the context variable and click Set Function.
- Define your custom function and choose a dimension.
- Click Add to Section.
- Click back into the sentence where you set your context variable.
- Add your first function and fill in the required fields. In this example, we selected DimensionValueLabel, and then chose Country/Region from Dimension, and then country with the highest GDP (our context variable) from Dimension Value.
- Click Add to Section.
- Add your second function and fill in the required fields. In this example, we selected Value, and then chose Country/Region from Dimension, SUM(Lending Interest) from Measure, and country with the highest GDP (our context variable) from Dimension Value.
- Click Add to Section.
- Click Save.
Your Data Story writes a sentence that gives us insight into a secondary measure (Lending Interest) for the country that we're interested in (the country with the highest GDP).
When to use a context variable: period-over-period analysis
A context variable is helpful when you want to analyze performance over two different periods in your Data Story. You can create a custom sentence that writes about a measure displayed in your drilldown section and compares the measure against different periods, such as year over year or month over month.
To set up a period-over-period analysis, your Data Story must have:
- 2 dimensions: 1 time period dimension (primary) and 1 non-time period dimension (secondary)
- 1–3 measures
- Create your Data Story.
- In the Fields dialog box, make sure your time period dimension is ordered first and click Next.
- In the Story dialog box, select Continuous and click Done.
- Open the Edit dialog box, and select Add Custom Item in the first drilldown area.
- Create two context variables that represent your time periods. For example, "Current Quarter" and "Previous Quarter."
- Create an increased sentence by adding custom language and functions. The content of this sentence results in "[CurrentDimensionValueLabel] increased [X%] over the quarter."
- Type in the function followed by the word "increased" in the custom text box.
- Add the function that returns the percent change of your measurement during your time period.
- Click Add to Section.
- Duplicate custom content and create a decreased version by replacing the word "increased" with "decreased." The functions stay the same.
- Add conditions for each sentence so that only one is written, depending on the data.
- For the increased sentence, set conditions in line with the following example:
Left Argument = Value function
Dimension = Quarter(OrderDate). Select your time period dimension
Measure = SUM(Total Orders). Select the measure you used for the calculation
Dimension Value = Current Quarter. One of the context variables
Filter Dimension Value = Current Region value (dynamic). This is the preset context variable
Middle Argument = > (greater than)
Right Argument = Value function
Dimension= Quarter(OrderDate). Select your time period dimension
Measure = Total(Total Orders). Select the measure you used for the calculation
Dimension Value = Previous Quarter. One of the context variables
Filter Dimension Value = Current Region value (dynamic). This is the preset context variable
- For the decreased sentence, set the same conditions, but replace the > (greater than) sign with the < (less than) sign. The right and left arguments remain the same.
- Click Save, and your Data Story writes a sentence that includes the insights from analyzing the two time periods.