IMPORTANT: This document is specific to Sigma's new Workbooks feature. If you instead want to learn about worksheet parameters, please visit Worksheet Parameters.

parameter is a customizable field that can be added to a workbook and referenced in formulas. They allow you to dynamically replace constant values used in calculations across your workbook. 

For example, you may want to compare product sales growth by a variable 2%, 5%, and 10% percent. A parameter can be used to quickly track this variable value and inject it into formulas. 

Summary of Content

Create a Parameter
Reference a Parameter in a Formula
Advanced Parameters
      Data Source Parameters
            Pass a Value to a Data Source Parameter
            EXAMPLE
      SQL Parameters
            Use a Parameter in SQL
Related Resources

Create a Parameter

  1. Click the + icon in the top right corner of the editor panel to open the new PAGE ELEMENTS view.
  2. Under the CONTROL ELEMENTS section of the ELEMENTS tab, click to select your intended control type.
    Your new element will appear on the page, and the editor panel will open up to the specific element’s configuration view.
  3. Under Control type, select Parameter
  4. Use the editor panel to configure the parameter's Settings

Reference a Parameter in a Formula

  1. Create a parameter.
    1.png
  2. Create and select a new column.
  3. Click to focus the formula bar.
  4. Type in your formula, formatting the parameter id in brackets (similar to columns). 4.png
  5. Click Enter to save your formula.5.png
  6. Once the formula is saved, changing the parameter value will automatically trigger the calculated column to re-calculate.6.png

Advanced Parameters

Data Source Parameters

Data source parameters are parameters that live on the workbook's data source but receive input from a parameter on the child workbook. 

Pass a Value to a Data Source Parameter

Data source parameters are accessible from the Source tab on a control's workbook editor panel view.

  1. Create a new workbook parameter, or select an existing one, to open the it in the workbook editor panel.
  2. Under the Settings tab, select a Value type to pass to your data source's parameter. The value type must match the data source parameters value type.
    Screen_Shot_2021-07-26_at_3.48.11_PM.png
  3. Open the workbook parameter's Source tab.
    Screen_Shot_2021-07-26_at_3.52.35_PM.png
  4. Click + Add Source. Then select your data source.
    Note: Only data sources containing one or more parameter(s) that accepts your selected value type will be available.
    Screen_Shot_2021-07-26_at_3.58.33_PM.png
  5. If the data source has more than one parameter, use the dropdown menu to select your target parameter. 
    Screen_Shot_2021-07-26_at_4.01.31_PM.png

EXAMPLE 

In the following example, [My Parameter] accepts a number value and passes it to a data source's parameter.

The table to the right of [My Parameter] is powered by the same data source. Its column, [+ 5 column], is calculated from the data source. The formula for [+ 5 column] adds 5 to the data source parameter: 

[data-source-parameter] + 5

When a value is input into [My Parameter], it is passed to the data source column and [+ 5 column] is recalculated with that value. 

0 + 5 = 5
3 + 5 = 8
10 + 5 = 15

2021-07-26_16-28-34__1_.gif

SQL Parameters

Workbook parameters can be included in written SQL.
Once a parameter is created, you can reference the value of that parameter in your SQL source by wrapping the parameter’s name within curly brackets: {{<parameter name>}}.

After the parameter is added to your SQL, a change to the parameter value will propagate to your SQL source and subsequently reload your worksheet to reflect your parameter use.

Use a Parameter in SQL

  1. Create a parameter.

  2. Identify your parameter's Control ID. This identifier will be referenced in your written SQL.

    Example: In the image below, the Control ID is "min-sales-amount".

    Screen_Shot_2021-07-27_at_2.32.03_PM.png

  3. Create a new data element from SQL. 

    • When writing your SQL, inject the parameter by referencing its control ID in double curly-brackets: {{<parameter name>}}.

      Example: {{min-sales-amount}}

      Screen_Shot_2021-07-27_at_2.37.40_PM.png

  4. After saving your SQL, you can test your new SQL parameter by inputting a value and watching the data element update accordingly.

 

Related Resources

Documentation

Intro to Control Elements

From the Sigma Community

Multi-select Parameters in Workbooks (hand-written SQL source)
Multi-select Parameters in Workbooks (Calculated Fields)