@@ -86,103 +86,9 @@ That last variable type, [Field Filter](#the-field-filter-variable-type), is spe
You can include multiple variables in the query, and Metabase will add multiple filter widgets to the question. When you have multiple filter widgets, you can click on a filter widget and drag it around to rearrange the order.
### Optional clauses
You can make a clause optional in a query. For example, you can create an optional `WHERE` clause that contains a SQL variable, so that if no value is supplied to the variable (either in the filter or via the URL), the query will still run as if there were no `WHERE` clause.
To make a clause optional in your native query, type `[[brackets around a {% raw %}{{variable}}{% endraw %}]]`. If you input a value in the filter widget for the `variable`, then the entire clause is placed into the template; otherwise Metabase will ignore the clause.
In this example, if no value is given to `cat`, then the query will just select all the rows from the `products` table. But if `cat` does have a value, like "Widget", then the query will only grab the products with a category type of Widget:
```sql
{%raw%}
SELECT
count(*)
FROM
products[[WHEREcategory={{category}}]]
{%endraw%}
```
To use multiple optional clauses, you must include at least one regular `WHERE` clause followed by optional clauses, each starting with `AND`:
```sql
{%raw%}
SELECT
count(*)
FROM
products
WHERE
TRUE
[[ANDid={{id}}]
[[AND{{category}}]]
{%endraw%}
```
That last clause uses a Field filter (note the lack of a column in the `AND` clause). When using a field filter, you must exclude the column in the query; you need to map the variable in the side panel.
If you're using MongoDB, you can make an clause optional like so:
In the variables sidebar, you can set a default value for your variable. This value will be inserted into the corresponding filter widget by default (even if the filter widget is empty). You'll need to insert a new value into the filter widget to override the default.
## Setting complex default values in the query
You can also define default values directly in your query by enclosing comment syntax inside the end brackets of an optional parameter.
The comment will "activate" whenever you pass a value to `your_parameter`.
This is useful when defining complex default values (for example, if your default value is a function like `CURRENT_DATE`). Here's a PostgreSQL example that sets the default value of a Date filter to the current date using `CURRENT_DATE`:
If you pass a value to the variable, the `WHERE` clause runs, including the comment syntax that comments out the default `CURRENT_DATE` function.
Note that the hash (`--`) used to comment the text might need to be replaced by the comment syntax specific to the database you're using.
## The Field Filter variable type
Setting a variable to the "Field Filter" type allows you to map the variable to a field in any table in the current database, and lets you create a "smart" filter widget that makes sense for that field.
Setting a variable to the **Field Filter** type allows you to map the variable to a field in any table in the current database. Field filters let you create a "smart" filter widget that makes sense for that field.
Field Filter variables should be used inside of a `WHERE` clause in SQL, or a `$match` clause in MongoDB.
...
...
@@ -198,7 +104,7 @@ Field Filters ONLY work with the following field types:
- State
- ZIP or Postal Code
The field can also be a date or timestamp, which can be left as "No semantic type" in the Table Metadata.
The field can also be a date or timestamp, which can be left as "No semantic type" in the [Table Metadata](../../data-modeling/metadata-editing.md).
When you set the **Variable type** to "Field Filter", Metabase will present an option to set the **Field to map to**, as well as the **Filter widget type**. The options available for the Filter widget type depend on the field's type. For example, if you map to a field of type Category, you'll see options for either "Category" or None. If you map to a Date Field, you'll see options for None, Month and year, Quarter and year, Single date, Date range, or Date filter.
...
...
@@ -276,16 +182,7 @@ If however, there are too many different values in that column to display in a d
Some things that could trip you up when trying to set up a Field Filter variable.
## Requiring a value for a filter widget
You can enforce a value of
In the **Variable** settings sidebar, you can toggle the **Always require a value** option. If you turn this on:
- You must enter a default value.
- The default value will override any optional syntax in your code (like an optional `WHERE` clause). If no value is passed to the filter, Metabase will run the query using the default value. Click on the **Eye** icon in the editor to preview the SQL Metabase will run.
### Table aliases
### Field Filters don't work with table aliases
You won't be able to select values from field filters in queries that use table aliases for joins or CTEs.
...
...
@@ -295,7 +192,7 @@ The reason is that field filters generate SQL based on the mapped field; Metabas
2. Replace CTEs with subqueries.
3. Create a view in your database, and use the view as the basis of your query.
### Include dependencies in your query
### Field Filters must be connected to fields included in the query
Your main query should be aware of all the tables that your Field Filter variable is pointing to, otherwise you'll get a SQL syntax error. For example, let's say that your main query includes a field filter like this:
...
...
@@ -324,16 +221,125 @@ WHERE
{%endraw%}
```
### SQL syntax
## Customizing dropdown lists and search box values
With Text and Field filter variables, you can tell Metabase what values people can choose from when using a filter with a dropdown list or search box.
Make sure your SQL dialect matches the database you've selected. Common errors:
1. In the native editor, add a {% raw %}{{variable}}{% endraw %} in double braces.
2. If the sidebar doesn't open, you can click on the **{x}** icon on the right to open the **Variables** sidebar.
3. In the **Settings** tab, set the **Variable type** to either "Text" or "Field Filter".
4. In the sidebar, go to **How should users filter on this variable?** Pick either **Dropdown list** or **Search box**.
5. Next to the option you chose, click **Edit**.
6. Metabase will pop up a modal where you can select **Where the values should come from**.
For more help, see [Troubleshooting SQL error messages](../../troubleshooting-guide/error-message.md#sql-editor).
-**From connected fields** If you selected the Field filter variable type, you'll also have the option to use the connected field.
-**From another model or question**. If you select this option, you'll need to pick a model or question, then a field from that model or question that Metabase will use to supply the values for that dropdown or search box. For example, if you want the dropdown to list the different plans an account could be on, you could select an "Account" model you created, and select the field "Plan" to power that dropdown. The dropdown would then list all of the distinct plan options that appear in the "Plan" column in the Accounts model.
-**Custom list**. Enter each item on a line. You can enter any string values you like.
You can also [change a dashboard filter's selectable values](../../dashboards/filters.md#change-a-filters-selectable-values).
## Setting a default value in the filter widget
In the variables sidebar, you can set a default value for your variable. This value will be inserted into the corresponding filter widget by default (even if the filter widget is empty). You'll need to insert a new value into the filter widget to override the default.
## Setting complex default values in the query
You can also define default values directly in your query by enclosing comment syntax inside the end brackets of an optional parameter.
The comment will "activate" whenever you pass a value to `your_parameter`.
This is useful when defining complex default values (for example, if your default value is a function like `CURRENT_DATE`). Here's a PostgreSQL example that sets the default value of a Date filter to the current date using `CURRENT_DATE`:
If you pass a value to the variable, the `WHERE` clause runs, including the comment syntax that comments out the default `CURRENT_DATE` function.
Note that the hash (`--`) used to comment the text might need to be replaced by the comment syntax specific to the database you're using.
## Requiring a value for a filter widget
In the **Variable** settings sidebar, you can toggle the **Always require a value** option. If you turn this on:
- You must enter a default value.
- The default value will override any optional syntax in your code (like an optional `WHERE` clause). If no value is passed to the filter, Metabase will run the query using the default value. Click on the **Eye** icon in the editor to preview the SQL Metabase will run.
## Making variables optional
You can make a clause optional in a query. For example, you can create an optional `WHERE` clause that contains a SQL variable, so that if no value is supplied to the variable (either in the filter or via the URL), the query will still run as if there were no `WHERE` clause.
To make a clause optional in your native query, type `[[brackets around a {% raw %}{{variable}}{% endraw %}]]`. If you input a value in the filter widget for the `variable`, then the entire clause is placed into the template; otherwise Metabase will ignore the clause.
In this example, if no value is given to `cat`, then the query will just select all the rows from the `products` table. But if `cat` does have a value, like "Widget", then the query will only grab the products with a category type of Widget:
```sql
{%raw%}
SELECT
count(*)
FROM
products[[WHEREcategory={{category}}]]
{%endraw%}
```
To use multiple optional clauses, you must include at least one regular `WHERE` clause followed by optional clauses, each starting with `AND`:
```sql
{%raw%}
SELECT
count(*)
FROM
products
WHERE
TRUE
[[ANDid={{id}}]
[[AND{{category}}]]
{%endraw%}
```
That last clause uses a Field filter (note the lack of a column in the `AND` clause). When using a field filter, you must exclude the column in the query; you need to map the variable in the side panel.
If you're using MongoDB, you can make an clause optional like so:
![metabase-bot[bot]'s avatar](https://secure.gravatar.com/avatar/5a54b0ee1ad6bf1b2f5cc0cf8d899cd3472359c55cfa3b55c0f005eea7c06b71?s=48&d=identicon "metabase-bot[bot]")
Jeff Bruemmer <jeff.bruemmer@gmail.com>