Parameters let report editors override default values in a data source. Using parameters makes a data source more flexible, and gives you another way to easily create report templates.
For example, a connector providing weather data could include a location parameter that lets editors request a weather report from a locale different than the default.In this article:
How data source parameters work
Data source parameters are available for data sources built with community connectors and the BigQuery connector.
For community connectors, the connector's developer defines which parameters to expose, and sets their default values. The connector's developer also determines which parameters can be modified in data sources. BigQuery users can include parameters in custom queries.
Once defined, data source parameters appear in 2 places: in the data source connection, and in the report:
In the data source connection
Parameters appear in the data source connection page. The example below shows what parameters for a weather data source might look like:
In this example, you can set new default values for the ZIP CODE and Units parameters. You can also specify which of these parameters can be modified in reports.
In the report
Modifiable parameters appear in a report component's DATA properties panel. You can also edit parameters in the report, page, and group properties panels.
Example of using parameters in a report
Let's say the weather connector provides 2 parameters: one for ZIP/postal code, and another for the temperature scale (Celsius vs. Fahrenheit). Both are set as modifiable in reports. The creator of the connector sets the default values to 94043 for the ZIP code, and Fahrenheit for the scale.
You create a data source using this connector. You decide to change ZIP code to 95060, and leave the default scale as Fahrenheit. You also allow both of these parameters to be modifiable in reports.
Next, you create a report from this data source and add a table showing the city and temperature fields. The table shows data for Santa Cruz, CA, with temperatures in Fahrenheit.
You then share the report with your colleague Sarah in London, giving her edit permission. Sarah edits the table's parameters to SW1A 1AA, and Celsius. The table updates to show the weather for the City of Westminster, with temperatures measured in Celsius.
How parameters share your data in reports
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.
Allow data source parameters in reports
To allow report editors to edit parameters:
- Sign in to Data Studio.
- In the top left, click , then select Data Source.
- Select a connector and, if necessary, authorize your 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 CONNECT.
Click CREATE REPORT in the upper right.
Modify parameters in a report
To change data source parameters in a chart or control:
- Edit the report.
- Add a new chart or control, or select an existing one.
- At the bottom of the chart or control's DATA tab, edit the parameter values.
You can also edit parameters at the report and page level:
- Edit the report.
- Select File > Report Settings or Page > Current Page Settings.
- Edit the parameter values.
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)
- Individual chart or control
You create a report using the example weather data source described above. This data source has a default ZIP code of 94043. If you add a table containing the City field to the report, it will inherit this value and display data for Mountain View, CA.
You then edit the report settings, and enter a ZIP code of 10011. Report level parameters are higher precedence than data source parameters, so the the table updates to show the weather for New York, NY.
Next, you edit the page settings, and set the ZIP code parameter to 90210. Page setting parameters are higher precedence than report and data source parameters, so the the table updates to show the weather for Beverly Hills, CA.
If you add a new table, it uses the highest precedence parameter, which is the current page setting of 90210.
Now, group the charts on the page. With the group selected, you can override both charts and set ZIP to 50475. Group level parameters are higher precedence than page, report, and data source parameters, so both charts now show the weather for Sheffield, IA.
Finally, select one of the tables and set its ZIP code parameter to 86023. Individual component parameters are higher precedence than group, page, report, and data source parameters, so that one table updates to show the weather for Grand Canyon, AZ.
Copy a component with parameters
Copying a component copies its parameters. You can override the copy's parameters by editing the component, as usual.
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.
Limits of data source parameters
Modifiable parameters are currently only available in community connectors and the BigQuery connector.
Report viewers can't modify data source parameters directly. However, if you've enabled date parameters for a BigQuery data source, and your report includes a date range control, viewers can use that control to request different starting and ending dates from the BigQuery data. Additionally, if you've enabled report URL parameters, those parameters can be changed by editing the report link.
Once you've created a data source, changes to the parameters in the 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.
As noted above, changes to parameters in the connector can cause errors in your charts.