Parameters let you interact with user-provided data. For example, you can create calculated fields that include input from people using your report, 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.
In this article: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 field lists in the report and data source editors. Parameters appear as purple fields.
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
You can create parameters in the following places:
In a data source
- Edit the data source.
- 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. - Configure the parameter's options and default value (see below).
In the BigQuery connector
You can pass parameters to a custom SQL query in the BigQuery connector. The BigQuery connector defines several standard parameters that pass the report's start and end date, and the user's email address, if available. You can also pass custom parameters. Learn more.
Parameters and Community connectors
Community connector can include overridable parameters, which let report editors modify their default values in a data source. If you can edit the connection for a data source built with a Community connector, you can specify which parameters report editors can change:
- Edit the data source.
- In the top left, click EDIT CONNECTION.
- 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.
- Use the Allow <parameter name> to be modified in reports checkboxes to allow or disallow editing the parameter in reports.
- In the top right, click RECONNECT.
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
Edit an existing parameter
To change the configuration of an existing parameter:
- Edit the data source that contains the parameter.
- Locate the parameter in the field list.
- Click the @ sign to the right of the parameter name.
- Make any changes, then in the bottom right, click SAVE.
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 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 Looker Studio to identify the parameter. Report viewers don't see it.
Data type: parameters can store text, numbers, or Boolean (true/false) values.
Permitted values: specifies the values that can be input by the user.
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.
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 users
Controls are components that let people interact with a report. To store user input in a parameter, add that parameter to a control's Control field property:
- Edit your report.
- At the top, click
Add a control.
- Choose the type of control to add.
In the Properties panel, select the SETUP tab.
- Add the parameter to the Control field.
Add a control.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:
- Edit your report.
- Select a component based on a data source that includes parameters.
- 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:
- Edit your report.
- Select File > Report Settings or Page > Current Page Settings.
- 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:
- Data source (default)
- Report
- Page
- Group
- 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.
Looker 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 users are allowed to modify:
- Edit your report.
- Select Resource > Manage report URL parameters.
- 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 someone enter a multiplier to your sales from last quarter.
First, create the parameter to hold the forecast multiplier:
- Sign into Looker Studio.
- Edit your data source.
- At the top right, click ADD A PARAMETER.
- Name the parameter (for example, "Forecast multiplier").
- Set the Data type to Number.
- 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. - Set the Default value to 1.
- Click Save.
- To return to the data source fields list, on the left, click ALL FIELDS.
Next, create the calculated field:
- At the top right, click ADD A FIELD.
- Name the field (for example, "Sales forecast with parameter").
- 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 - Click Save.
Next, add a control to gather the user's input:
- Edit or create a report.
- If necessary, add your data source to the report.
- At the top, click
- Select the Input box control.
The Input box control lets you type in parameter values directly. Other types of controls let you select from a list, use a slider, or toggle Boolean values with a checkbox. - On the right, in DATA properties, add the Forecast multiplier parameter you created previously.
Finally, visualize the parameterized calculated field in a chart.
- At the top, click
Add a chart.
- For simplicity, select a Scorecard.
- On the right, in DATA properties, add the Sales forecast with parameter calculated field as the Metric.
Add a chart.Now, try it out:
- At the top right, click View.
- Enter a number in the Forecast multiplier control, then press Enter.
- 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:
- Edit your data source.
- Locate the parameter.
- To the right of the parameter, click
Options.
- Click Show (if the parameter is currently hidden) or Hide (if the parameter is currently shown).
Options.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.