[auto] adding content to docs-filters-in-headings-and-dashcards->master

Author: Metabase Docs bot

_docs/master/dashboards/filters.md

@@ -16,30 +16,15 @@ redirect_from:
 
 ![Dashboard Filters](./images/filters.png)
 
-Have you ever found yourself in a situation where it seems like you need to create nearly identical copies of the same dashboard, with just one different variable? Maybe you have an Earnings dashboard, but you want to see the data for each city your business is in, or maybe you have a KPI dashboard that you want to see broken out by month.
+Instead of creating duplicate dashboards to show different cuts of the same data (like a different dashboard for each quarter), you can add filter or parameter widgets to let people change _what_ data is displayed (filter the data), or _how_ its displayed (parameterize the data).
 
-Instead of creating duplicate dashboards, you can add filter or parameter widgets to let people change variables for cards on a dashboard.
+## Filter and parameter widgets
 
-## Adding a filter or parameter
-
-![Add a Filter](./images/add-filter.png)
-
-- Click the **pencil icon** to enter dashboard editing mode.
-- Click the **filter icon** that appears in the top-right to add a filter.
-- Select a [filter type](#filter-and-parameter-types)
-- [Connect your filter or parameter widget to dashboard cards](#connecting-a-filter-or-parameter-widget-to-dashboard-cards) to one or more dashboard cards on any or all tabs.
-- [Configure your filter](#editing-a-filter)
-- **Save** your changes.
-
-Metabase will display the filter only if the filter is connected to a card on the current dashboard tab.
-
-## Filter and parameter types
-
-The type of filter or parameter widget you choose determines how the widget works, including which fields you'll be able to filter your cards by.
+There are two basic types of widgets you can add. The type of filter or parameter widget you choose determines how the widget works, including which fields you'll can connect to the widget.
 
 ### Filter widgets
 
-**Filters** determine what data to show. For example, a date filter might show only data from the last 30 days, or a category filter might show only specific product categories.
+**Filters** determine _what_ data to show. For example, a date filter might show only data from the last 30 days, or a category filter might show only specific product categories.
 
 - [Date picker](#date-picker-filters)
 - [Location](#location-filters)
@@ -50,13 +35,45 @@ The type of filter or parameter widget you choose determines how the widget work
 
 ### Parameter widgets
 
- **Parameters** determine how to show the data. The time grouping parameter, for example, changes the granularity of time-based visualizations (like showing data by month instead of by day) without removing any data points.
+ **Parameters** determine _how_ to show the data. The time grouping parameter, for example, changes the granularity of time-based visualizations (like showing data by month instead of by day) without removing any data points.
 
 - [Time grouping](#time-grouping-parameter)
 
+## Adding a filter or parameter widget
+
+![Add a Filter](./images/add-filter.png)
+
+1. Click the **pencil icon** to enter dashboard editing mode.
+2. You can add a filter or parameter widget to:
+    
+    - **The whole dashboard**. Metabase will only display dashboard-level widgets if they're connected to a card on the current tab.
+    - **Heading cards**. Not text cards, only [heading cards](./introduction#adding-headings-or-descriptions-with-text-cards). Can only be connected to cards on the current tab.
+    - **Question cards**. Can only be connected to cards on the current tab.
+   
+   Go to where you want to add a filter and click the **filter icon**.
+3. Select a [filter type](#filter-and-parameter-types).
+4. [Connect your filter or parameter widget to dashboard cards](#connecting-a-filter-or-parameter-widget-to-dashboard-cards) to one or more dashboard cards. Only dashboard-level widgets can be connected to cards on multiple tabs.
+5. [Configure your filter](#editing-a-filter).
+6. **Save** your changes.
+
+Metabase will display the filter only if the filter is connected to a card on the current dashboard tab.
+
+### When to add a widget to a heading or card
+
+These are just rules of thumb to keep the user experience predictable. Do whatever works for your use case.
+
+By default, you should add widgets to the dashboard itself.
+
+If, however, your dashboard grows larger, and it doesn't make sense to break the dashboard up into multiple dashboards, you can add widgets to headings and cards so people can filter in place as they scroll through sections. In these cases, you should scope the effects of a heading widget to the section immediately below. Filters on cards should generally only update the card itself.
+
+If you want tab-specific widgets, you could either:
+
+- Add them to the dashboard itself, but only connect the widget to cards on a specific tab.
+- Use a heading filter.
+
 ## Date picker filters
 
-When picking a Time filter, Metabase will prompt you to pick a specific type of date picker widget:
+When picking a Date picker filter, Metabase will prompt you to pick an operator:
 
 - Month and Year
 - Quarter and Year
@@ -65,19 +82,17 @@ When picking a Time filter, Metabase will prompt you to pick a specific type of
 - Relative Date
 - All Options
 
-Single Date and Date Range will provide a calendar widget, while the other options all provide slightly different dropdown interfaces for picking values. To get a widget that's just like the time filter in the query builder, choose All options.
+Single Date and Date Range will provide a calendar widget, while the other options all provide slightly different dropdown interfaces for picking values. To get a widget that's just like the date picker in the query builder, choose All options.
 
 ## Time grouping parameter
 
 ![Time grouping](./images/time-grouping.png)
 
-You can add a time grouping widget to a dashboard to change how charts are grouped by time. For example, you may want to look at the time series charts grouped by month by default, but give people the option to view the results by other groupings: by week, by quarter, and so on.
-
-> Time grouping parameter widget can only be connected to questions built with the [graphical query builder](../questions/query-builder/editor).
+You can add a time grouping widget to a dashboard to change how charts are grouped by time. This widget won't filter the data; it'll change how Metabase displays the data. For example, you may want to look at the time series charts grouped by month by default, but give people the option to view the same results by other groupings: by week, by quarter, and so on.
 
 This widget doesn't filter data in the charts; the widget just changes the time granularity for any cards that have a datetime field connected to the widget.
 
-You can group by:
+Grouping options include:
 
 - Minute (or minute of hour)
 - Hour (or hour of day)
@@ -87,6 +102,8 @@ You can group by:
 - Quarter (or quarter of year)
 - Year
 
+To connect a time grouping widget to a SQL question, you'll need to insert time grouping parameters in your code. See [time grouping parameters](../questions/native-editor/time-grouping-parameters).
+
 ## Location filters
 
 There are four types of Location filters to choose from:
@@ -96,10 +113,21 @@ There are four types of Location filters to choose from:
 - ZIP or Postal Code
 - Country
 
+Additionally, you can select an operator for the location filter:
+
+- **Is**. Select one or more values from a list or search box. Use **Is** when you just want to plug a value into a variable. For multiple values, the card must be either a question built using the query builder, or a native/SQL question using a [field filter](../questions/native-editor/sql-parameters#field-filter-variables).
+- **Is not**. Exclude one or more specific values.
+- **Contains**. Match values that contain the entered text.
+- **Does not contain**. Filter out values that contain the entered text.
+- **Starts with**. Match values that begin with the entered text.
+- **Ends with**. Match values that end with the entered text.
+
 ## ID filter
 
 The ID filter provides a simple input box where you can type the ID of a user, order, etc.
 
+You can give people the option to pick one value or multiple values.
+
 ## Number filter
 
 You can choose from:
@@ -114,21 +142,25 @@ You can choose from:
 
 A flexible filter type that will let you create either a dropdown menu or an input box to filter on any category field in your cards. Options include:
 
-- **Is**. Select one or more values from a list or search box. Use **Is** when you just want to plug a value into a variable. For multiple values, the card must be either a question built using the query builder, or a native/SQL question using a [field filter](../questions/native-editor/sql-parameters#the-field-filter-variable-type).
+- **Is**. Select one or more values from a list or search box. Use **Is** when you just want to plug a value into a variable. For multiple values, the card must be either a question built using the query builder, or a native/SQL question using a [field filter](../questions/native-editor/sql-parameters#field-filter-variables).
 - **Is not**. Exclude one or more specific values.
 - **Contains**. Match values that contain the entered text.
 - **Does not contain**. Filter out values that contain the entered text.
 - **Starts with**. Match values that begin with the entered text.
 - **Ends with**. Match values that end with the entered text.
 
+You can also select how people should filter on this column:
+
+- Dropdown list
+- Search box
+- Input box
+
 ## Boolean filter
 
 A boolean filter allows people to filter data based on true/false values.
 
 ## Connecting a filter or parameter widget to dashboard cards
 
-Dashboard widgets apply across all [dashboard tabs](./introduction#dashboard-tabs), though they'll only be displayed when a tab has cards connected to the widget.
-
 For each widget that you add, you'll need to tell Metabase which column the filter should update for each card.
 
 Click on a card's dropdown menu to select the field that you want the widget to filter on.
@@ -137,6 +169,11 @@ Here we've wired up a Text filter to the "Event types" card, telling Metabase th
 
 ![Wiring up a dashboard filter to a card](./images/wiring-cards.png)
 
+Which cards you can connect a filter or parameter widget to depends on:
+
+- Whether the question card has the relevant field.
+- Where the widget is located: on the dashboard, heading card, or question card. Only dashboard widgets can be connected to cards across all [dashboard tabs](./introduction#dashboard-tabs). Widgets on heading and question cards are restricted to the cards on their respective tabs.
+
 ## Auto-connecting filters to cards
 
 If there are other cards that also have the field you select, Metabase will offer to automatically connect the filter to those cards too (including to relevant cards on other tabs). If you later add a card with the selected field, Metabase will also try to connect that filter to the new card.
@@ -145,9 +182,9 @@ To undo this auto-connecting of cards, click on the toast that pops up when Meta
 
 ## Filtering dashboards with native/SQL questions
 
-If you're trying to connect a filter to a card with a native/SQL questions, you'll need to [add a variable or field filter to your query](../questions/native-editor/sql-parameters). For an in-depth article, check out [Adding filters to dashboards with SQL questions](/learn/metabase-basics/querying-and-dashboards/sql-in-metabase/filters).
+For filters, you'll need to [add a variable or field filter to your query](../questions/native-editor/sql-parameters). 
 
-You can't connect a time grouping parameter widget to a card with a SQL question.
+For parameters, check out [Time grouping parameters](../questions/native-editor/time-grouping-parameters).
 
 ## Wiring up dashboard filters to text cards
 
@@ -201,8 +238,8 @@ A list of all of the possible values in a column. People can use checkboxes to s
 
 If you're not seeing the **Dropdown list** option, and your dashboard filter is based on a column from a:
 
-- Table or GUI model: an admin will need to [enable the dropdown widget](../data-modeling/metadata-editing#changing-a-search-box-filter-to-a-dropdown-filter) for that column from Metabase's **Admin settings**.
-- SQL model: go to your [model's metadata settings](../data-modeling/models#add-metadata-to-columns-in-a-model), find your column, and set the **Database column this maps to**.
+- Table or model built with the query builder: an admin will need to [enable the dropdown widget](../data-modeling/metadata-editing#changing-a-search-box-filter-to-a-dropdown-filter) for that column from Metabase's **Admin settings**.
+- Model built with a SQL query: go to your [model's metadata settings](../data-modeling/models#add-metadata-to-columns-in-a-model), find your column, and set the **Database column this maps to**.
 
 #### Search box
 

_docs/master/dashboards/linked-filters.md

@@ -63,7 +63,7 @@ Metabase uses database column metadata to populate values for linked filters, wh
 
 - You can't create linked filters on custom columns.
 
-- Native/SQL questions must have a [field filter](../questions/native-editor/sql-parameters#the-field-filter-variable-type) variable in order to be linked. Basic SQL variables aren't connected to database columns, so they won't work for linked filters.
+- Native/SQL questions must have a [field filter](../questions/native-editor/sql-parameters#field-filter-variables) variable in order to be linked. Basic SQL variables aren't connected to database columns, so they won't work for linked filters.
 
 - You can't link filters that use "Custom List" or "From another model or question" as their value's source.
 

_docs/master/data-modeling/field-types.md

@@ -173,7 +173,7 @@ When you [X-ray](../exploration-and-organization/x-rays) a table, model, or enti
 
 ### Field Filters
 
-Knowing what field types are and how they work is helpful when using [field filters](/learn/metabase-basics/querying-and-dashboards/sql-in-metabase/field-filters), as you can only create field filters for [certain field types](../questions/native-editor/sql-parameters#field-filter-compatible-types).
+Knowing what field types are and how they work is helpful when using [field filters](/learn/metabase-basics/querying-and-dashboards/sql-in-metabase/field-filters), as you can only create field filters for [certain field types](../questions/native-editor/sql-parameters#field-filters-are-only-compatible-with-certain-types).
 
 ### JSON unfolding
 

_docs/master/questions/images/02-widget.png

@@ -0,0 +1,78 @@
+---
+version: master
+has_magic_breadcrumbs: true
+show_category_breadcrumb: true
+show_title_breadcrumb: true
+category: Questions
+title: 'Basic SQL parameters'
+source_url: 'https://github.com/metabase/metabase/blob/master/docs/questions/native-editor/basic-sql-parameters.md'
+layout: new-docs
+summary: 'Text, number, and date variables let you plug basic values into your SQL code.'
+---
+
+# Basic SQL parameters
+
+> If you want to filter on a database field in your query, you should prefer using [field filter variables](./sql-parameters), which require a different syntax.
+
+To add a basic variable to a SQL query, enclose the variable in double braces: `{% raw %}{{variable_name}}{% endraw %}`.
+
+This example defines a **Text** variable called `category_filter` (but you can call the variable whatever you want):
+
+```sql
+{% raw %}
+SELECT
+  count(*)
+FROM
+  products
+WHERE
+  category = {{category_filter}}
+{% endraw %}
+```
+
+These basic variables (that just allow basic string/number interpolation) have a different syntax than [field filters](./sql-parameters).
+
+Here's the [field filter](./sql-parameters#field-filter-variables) syntax:
+
+```sql
+{% raw %}
+WHERE
+  {{category}}
+{% endraw %}
+```
+
+Whereas the basic variable syntax includes an `=` operator:
+
+```sql
+{% raw %}
+WHERE
+  category = {{category}}
+{% endraw %}
+```
+
+Here, we don't connect the variable to a database field; we merely insert the value into the variable.
+
+Metabase will read the variable and attach a filter widget to the query, which people can use to change the value inserted into the `category` variable. So if someone enters "Gizmo" into the filter widget, the query Metabase would run would be:
+
+```sql
+SELECT
+  count(*)
+FROM
+  products
+WHERE
+  category = 'Gizmo'
+```
+
+If you're writing a native MongoDB query, your query would look more like this, with the `category` variable being defined inside the `match` clause:
+
+```
+{% raw %}[{ $match: { category: {{category}} } }]{% endraw %}
+```
+
+## Basic SQL variables offer limited options for filter types
+
+- **Text**: a plain input box
+- **Number**: a plain input box
+- **Date**: a simple date picker
+- **Boolean**: a this or that picker.
+
+If you want a more expressive filter widget, like a dynamic date picker, you should use a [field filter variable](./sql-parameters#field-filter-variables).