Parameter
What is a parameter?
A parameter is a special type of variable that specifies an input to a query.
Setting a parameter lets end users input a value (like in a dashboard or report) to change what data that query returns, typically filtering by a measure or dimension. The parameter passes that value through to the query being run, and the results of that query will depend on whatever value that person entered.
Parameter vs. variable vs. argument
You may see “parameter” used interchangeably with “variable” or “argument,” so it’s worth pointing out some distinctions here. A parameter is a type of variable; it’s just one where some specific input value gets passed along to the program or query being run. Not all variables are parameters, though — you may also have variables that are set within your program or query and can’t be modified by anyone on the other side.
An argument refers to the value itself that gets passed along when your program or query runs. For example, if you set a parameter as {{productID}}
, and enter a value of 34
, your argument is 34. A parameter defines that there will be an input value, but the input value itself is the argument.
So yes, technically these terms all differ, but it’s okay to use them interchangeably, as long as you’re generally referring to a place or container to pass values into so you can filter results.
Parameters in Metabase
In Metabase, you can set a parameter using a filter widget or via a URL. Parameters come into play in Metabase in a few different ways:
SQL templates
By adding parameters to SQL queries in Metabase, you can create SQL templates that add filter widgets to those queries, allowing people to easily change that parameter’s value when they run that query.
If we wanted to create a SQL template on a query that counted the number of customers in each state using the Sample Database’s People
table, we’d use:
SELECT count(*)
FROM people
WHERE state = {{State}}
By wrapping {{State}}
in double curly brackets, we’ve created a parameter that adds a filter widget to this question, letting people input the state they want without needing to change the text of the query itself, like in figure 1:
Dashboard filters
Dashboard filters let you set parameters that get applied to a dashboard. For example, you can create a dashboard filter that lets people input a State
value and link that that filter to the State
column in the questions or cards on your dashboard. Then when people enter the value they want (like North Carolina, shown in figure 2), they’ll see those cards change accordingly.
When you enter a value into a dashboard filter, you’ll notice that the URL changes to include that value.
Custom destinations
You can also insert parameters into a URL to dictate what happens when people click on a chart in a dashboard. For example, you can set a custom destination by using values from the card’s results to construct a URL that directs people to another dashboard or external site with that ID as part of the URL.
Maybe you have a dashboard containing questions that track how different products in your inventory have sold, and a dashboard filter that lets people input the product they want to check in on. You could take things a step further by passing that product’s ID onto a custom destination, parameterizing a URL with that ID value and sending people to that product’s page on your website. When you visit that site, its URL may look something like this:
https://www.your-website.com/products/id?productID=34
In this case, that productID=34
in the URL is your parameter.
Embedding
When embedding Metabase questions and dashboards in your app, you can set parameters to customize what different users see when viewing those embeds.