Parameters

Pass user-supplied data to calculated fields and connectors.

Parameters let you interact with user-provided data. For example, you can create calculated fields that include input from your viewers, or pass values back to the SQL query used by your data source. Using parameters makes your reports more interactive. You can also use parameters to create report templates.

How parameters work

Parameters act like variables in a programming language. Parameters serve 3 primary uses:

  • You can use parameters in calculated fields to display results based on user input.
  • You can pass parameters back to the custom SQL query in a BigQuery data source.
  • You can pass parameters back to a community connector.

Parameters can get their data from the following places:

  • From a default value defined for the parameter.
  • From the component properties panel.
  • From a control placed on the report.
  • From the link to the report.

You'll find parameters at the bottom of the list of available fields in the report and data source editors. Parameters appear as purple fields.

Available fields list, showing dimensions, metrics, and parameters.

 

How parameters share your data in reports

Editors of your reports and data sources can access any data that is controlled by parameters.

Parameters let report editors request data that differs from the default. Before you enable parameters for your data source, be sure you understand how changes to parameter values could affect the data in your reports. Some parameters may only return relatively "safe" data, like weather in a new locale. Other parameters, however, might allow someone to request entirely new data sets. For example, an account number parameter, or name of a database table would potentially return data you didn't intend to share, or perhaps return a different schema, which might be incompatible with existing charts in the report.

Create a parameter

There are several places where you can create parameters:

In a data source

  1. Sign into Data Studio.
  1. Edit a data source.
  2. In the upper right, click ADD A PARAMETER.
    You can also create a parameter while editing a report by selecting a component, then in the bottom right, clicking ADD A PARAMETER. Be sure to select a component based on the desired data source.
  3. Configure the parameter's options and default value (see below).

In BigQuery and Community connectors

BigQuery and Community connectors let you create and use parameters. These parameters appear in the data source connection page. 

You can pass parameters to a custom SQL query in the BigQuery connector. The BigQuery connector defines several system parameters that pass the report's start and end date, and the viewer's email address, if available. You can also pass custom parameters. Learn more.

A community connector can define parameters and set their default values. The community connector can allow these parameters to be modified in data sources built with that connector.

To allow report editors to edit parameters set in the connector:

  1. Sign in to Data Studio.
  2. In the top left, click , then select Data Source.
  3. Select a connector and, if necessary, authorize your connection.
  4. If the connector provides editable parameters, they appear at the bottom of the page. Connectors that allow you to define custom parameters will include instructions on the page.
  5. Use the Allow <parameter name> to be modified in reports checkboxes to allow or disallow editing the parameter in reports.
  6. In the top right, click CONNECT.
  7. Click CREATE REPORT in the upper right.

Once you've created a data source from a community connector, changes to the parameters in that connector won't appear in the data source automatically. You'll need to reconnect the data source to see any new, removed, or changed parameters

Learn more.

Configure a parameter

Use these options to configure a parameter in the data source. For BigQuery connector and community connector parameters, see the articles referenced above.

Parameter name: you'll see this name in the lists of available fields in your reports and data sources. This is also the name you'll use to refer to the parameter in a calculated field.

Parameter ID: set by default. The parameter ID is used internally by Data Studio to identify the parameter. Report viewers don't see it.

Changing the Parameter ID will break components and calculated fields that include the parameter.

Data type: parameters can store text, numbers, or Boolean (true/false) values.

Permitted values: specifies the values that can be input by the viewer.

To specify a list of values, choose that option, then enter the acceptable value, along with an optional display name. Click Add option to add more items to the list.

To specify a range of permitted values, enter the minimum and maximum values for the range.

Default value: specify a starting value for the parameter.

Edit an existing parameter

To change the configuration of an existing parameter:

  1. Edit the data source that contains the parameter.
  2. Locate the parameter in the field list.
  3. Click the @ sign to the right of the parameter name.
  4. Make any changes, then in the bottom right, click SAVE.

Set parameter values

You can set the value of a parameter in the following ways:

Set a default value for the parameter

You can set default values for a parameter when you create it. To adjust the default value, follow the steps above to edit the parameter.

Use a control to get input from report viewers

Controls are components that let viewers interact with a report. To store user input in a parameter, add that parameter to a control's Control field property:

  1. Sign in to Data Studio.
  2. Edit a report.
  3. At the top, click Dimension Filter iconAdd a control.
  4. Choose the type of control to add.
  5. On the right, in DATA properties, add the parameter to the Control field.

Learn more about controls.

Override default parameter values in a component

You can override the default values for parameters by editing individual components in the report:

  1. Edit the report.
  2. Select a component based on a data source that includes parameters.
  3. At the bottom of the component's DATA tab, edit the default parameter values.

You can also edit parameters at the report and page level:

  1. Edit the report.
  2. Select File > Report Settings or Page > Current Page Settings.
  3. Edit the parameter values.

Parameter inheritance

Parameters follow the same rules for inheritance as filter properties. Specifically, parameters on higher precedence components override the parameters on lower precedence components. The order of precedence (from lowest to highest) is:

  1. Data source (default)
  2. Report
  3. Page
  4. Group
  5. Individual chart or control

Modify parameters via the report link

Setting parameters via the report's URL lets developers and advanced users to construct reports that can be configured programmatically.

Data Studio report parameters and their corresponding values are passed in as URL encoded JSON strings appended to report URL using the "params" query parameter.

Learn more in the Developer Guide.

Manage report URL parameters

Parameters in your reports are not editable via the report URL by default.

To select which parameters report viewers are allowed to modify:

  1. Edit the report.
  2. Select Resource > Manage report URL parameters.
  3. In the Allow setting through report URL column check the parameters you want to allow.

This page also displays the URL parameter for each parameter. This is the name you'll use, not the Parameter name, when you construct the encoded parameter object. You can edit this name by clicking the edit pencil. Every URL parameter in a report must be unique.

Editing the URL parameter name has no effect on how the parameter is used in the report.

Use parameters

Once created, you can use parameters in calculated fields and report components much as you would dimensions and metrics.

Use a parameter in a calculated field

You can use a parameter just as you'd use a dimension or metric in a calculated field.

Calculated field with parameter example

For example, say you want to visualize forecasted sales by letting the report viewer enter a multiplier to your sales from last quarter.

First, create the parameter to hold the forecast multiplier:

  1. Sign into Data Studio.
  2. Edit your data source.
  3. At the top right, click ADD A PARAMETER.
  4. Name the parameter (for example, "Forecast multiplier").
  5. Set the Data type to Number.
  6. For simplicity, leave the Permitted values option set to Any value.
    You can use the other options to let the user pick from a list of values, or restrict their entry to a range of values.
  7. Set the Default value to 1.
  8. Click Save.
  9. To return to the data source fields list, on the left, click ALL FIELDS.

Next, create the calculated field:

  1. At the top right, click ADD A FIELD.
  2. Name the field (for example, "Sales forecast with parameter").
  3. In the formula, multiply the "Sales" field from your data source by the Forecast multiplier parameter. For example, if your data source has a field called Revenue, enter:
    Revenue * Forecast multiplier
  4. Click Save.

Next, add a control to gather the user's input:

  1. Edit or create a report.
  2. If necessary, add your data source to the report.
  3. At the top, click Dimension Filter iconAdd a control.
  4. Select the Input box control.
    The Input box control lets viewers type in parameter values directly. Other types of controls let viewers select from a list, use a slider, or toggle Boolean values with a checkbox.
  5. On the right, in DATA properties, add the Forecast multiplier parameter you created previously.

Finally, visualize the parameterized calculated field in a chart.

  1. At the top, click Add chart icon. Add a chart.
  2. For simplicity, select a Scorecard.
  3. On the right, in DATA properties, add the Sales forecast with parameter calculated field as the Metric.

Now, try it out:

  1. At the top right, click View.
  2. Enter a number in the Forecast multiplier control, then press Enter.
  3. You'll see the value in the scorecard change as it is multiplied by the value you enter.

Use a parameter in a visualization

You can add a parameter to a chart, just as you would a dimension or metric. If you use a numeric parameter as a metric, its value is aggregated.

Show / hide parameters in reports

You can show or hide parameters you've created in a data source:

  1. Edit your data source.
  2. Locate the parameter.
  3. To the right of the parameter, click More menu Options.
  4. Click Show (if the parameter is currently hidden) or Hide (if the parameter is currently shown).
Hiding a parameter removes it from the list of available fields in the report properties panel, and will break any components that use it. If the parameter is used in a calculated field, the formula uses the parameter's default value.

Copy a component with parameters

Copying a component copies its parameter values as set in the property panel. You can override the copy's parameters by editing the component.

Fix invalid parameters

If the parameter configuration changes in the connector, any charts using those parameters may break. For example, the connector's developer may remove the ability to override a parameter value, and the value you've provided in the report no longer returns valid data. In this case, you'll see an error message in any charts impacted by that change.

To fix this, locate the component containing the now-invalid parameter. Then, in the Parameters section of that component's DATA properties, click Fix Invalid Values.

Remember that parameters can be set at the report, page, and group level, as well as on individual charts, so you may need to look in several places to find and fix the error.

About controls

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue