Customize Your Tableau Data Story: Context Variables

Applies to: Tableau Cloud, Tableau Desktop

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

  1. In your Data Story, click Edit to open the Edit dialog box.
  2. Click Add Custom Item.
  3. Click the menu in the right side of your custom content box and select Set context.

    Edit story dialog box where one story sentence is selected, so the menu is open. The “Set context” option is highlighted.

  4. Click Add context.
  5. Name the context variable and click Set Function.
  6. Define your custom function and choose a dimension.

    An open field for naming a context variable, an “Add context” button, and fields for defining the custom function.

  7. Click Add to Section.
  8. Click back into the sentence where you set your context variable.
  9. Follow the steps to Add functions.

    The function dialog box is open, and the field for defining the custom function has the custom context options listed.

Now, your context variable is listed as an option in the Dimension Value drop-down list when adding your function.

When to use a context variable: reference two or more measures

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
  1. In your Data Story, click Edit to open the Edit dialog box.
  2. Click Add Custom Item.
  3. Click the menu in the right side of your custom content box and select Set context.
  4. Click Add context.
  5. Name the context variable and click Set Function.
  6. Define your custom function and choose a dimension.
  7. Click Add to Section.

    Image that shows a context variable with a defined function of sort descending label, measure of SUM(GDP), Rank 1, and Dimension of Country/Region

  8. Click back into the sentence where you set your context variable.
  9. 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.

    The function dialog box is open, and the options listed in step 9 are selected.

  1. Click Add to Section.
  2. 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.

    The function dialog box is open, and the options listed in step 10 are selected.

  1. Click Add to Section.
  2. 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).

Image that shows a sentence rendered in the data story stating that the United States has the highest AVG (GDP) and a lending interest of $0.7B in this data set.

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
  1. Create your Data Story.
  2. In the Fields dialog box, make sure your time period dimension is ordered first and click Next.
  3. In the Story dialog box, select Continuous and click Done.
  4. Open the Edit dialog box, and select Add Custom Item in the first drilldown area.
  5. Create two context variables that represent your time periods. For example, "Current Quarter" and "Previous Quarter."

    Image that shows two context variables set, one for a current quarter and one for a previous quarter

  6. Create an increased sentence by adding custom language and functions. The content of this sentence results in "[CurrentDimensionValueLabel] increased [X%] over the quarter."
  7. Type in the function followed by the word "increased" in the custom text box.
  8. Add the function that returns the percent change of your measurement during your time period.

    The function dialog box is open, and the options listed in step 1 through 8 are chosen.

  9. Click Add to Section.
  10. Duplicate custom content and create a decreased version by replacing the word "increased" with "decreased." The functions stay the same.

    Edit story dialog box where one story sentence is selected, so the menu is open. The “Duplicate” option is highlighted.

  11. Add conditions for each sentence so that only one is written, depending on the data.

    The condition dialog box is open, and custom content is entered for the increase from the previous quarter.

  12. 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

The condition dialog box is open, and custom content is entered as described in step 12.

  1. 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.
  2. Click Save, and your Data Story writes a sentence that includes the insights from analyzing the two time periods.


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!