docs - update field filters (#28232)

docs/questions/native-editor/sql-parameters.md

@@ -198,6 +198,7 @@ A MongoDB native query example might look like this:
 ```
 {% raw %}[ {$match: {{date_var}} } ]{% endraw %}
 ```
+
 For a more in-depth guide, check out [Field Filters: create smart filter widgets for SQL questions][field-filter].
 
 ## How to create different types of filter widgets
@@ -237,21 +238,19 @@ If the field you want to create a dropdown for is not set to the type "Category"
 
 If however, there are too many different values in that column to display in a dropdown menu, Metabase will simply display a search box instead. So if you have a lot of email addresses, you may just get a search box anyway. The dropdown menu widgets work better when there's a small set of values to choose from (like the fifty U.S. states).
 
-## Field filter gotchas
-
-Some things that could trip you up when trying to set up a Field Filter variable:
-
-### Field filters don't work with table aliases
+## Field filter limitations
 
-Table aliases are not supported. The reason is that field filters generate SQL based on the mapped field; Metabase doesn't parse the SQL, so it can't tell what an alias refers to.
+Some things that could trip you up when trying to set up a Field Filter variable.
 
-The workaround is to either avoid aliases and use full table names, or instead use a subquery, for example, a query nested inside a SELECT statement. Alternatively, you could create a view in your database that shows the results of a complicated query, and then query that view.
+### Table aliases
 
-### Some databases require the schema in the FROM clause
+You won't be able to select values from field filters in queries that use table aliases for joins or CTEs.
 
-An example for **BigQuery**, back ticks are needed, like `` FROM `dataset.table` ``. If "Project ID (override)" is used in the connection settings, then it should be `` FROM `project.dataset.table` ``.
+The reason is that field filters generate SQL based on the mapped field; Metabase doesn't parse the SQL, so it can't tell what an alias refers to. You have three options for workarounds, depending on the complexity of your query.
 
-For **Oracle** it would be `FROM "schema"."table"`.
+1. Use full table names.
+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
 
@@ -261,23 +260,34 @@ Your main query should be aware of all the tables that your Field Filter variabl
 SELECT *
 FROM ORDERS
 WHERE {% raw %}{{ product_category }}{% endraw %}
-``` 
+```
 
 Let's say the `{% raw %}{{ product_category }}{% endraw %}` variable refers to another question that uses the `Products` table. For the field filter to work, you'll need to include a join to `Products` in your main query.
 
 ```
 SELECT *
-FROM ORDERS o
-JOIN PRODUCTS p
-ON o.product_id = p.id
+FROM ORDERS
+JOIN PRODUCTS
+ON ORDERS.product_id = PRODUCTS.id
 WHERE {% raw %}{{ product_category }}{% endraw %}
 ```
 
+### SQL syntax
+
+Make sure your SQL dialect matches the database you've selected. Common errors:
+
+| Database | Do this                    | Avoid                |
+| -------- | -------------------------- | -------------------- |
+| BigQuery | `` FROM `dataset.table` `` | `FROM dataset.table` |
+| Oracle   | `FROM "schema"."table"`    | `FROM schema.table`  |
+
+For more help, see [Troubleshooting SQL error messages](../../troubleshooting-guide/error-message.md#sql-editor).
+
 ## Connecting a SQL question to a dashboard filter
 
 In order for a saved SQL/native question to be usable with a dashboard filter, the question must contain at least one variable.
 
-The kind of dashboard filter that can be used with the SQL question depends on the field. For example, if you have a field filter called `{% raw %}{{var}}{% endraw %}` and you map it to a State field, you can map a Location dashboard filter to your SQL question. In this example, you'd create a new dashboard (or go to an existing dashboard), click the __Pencil icon__ to enter __Dashboard edit mode__, add the SQL question that contains your State Field Filter variable, add a new dashboard filter (or edit an existing Location filter), then click the dropdown on the SQL question card to see the State Field Filter.
+The kind of dashboard filter that can be used with the SQL question depends on the field. For example, if you have a field filter called `{% raw %}{{var}}{% endraw %}` and you map it to a State field, you can map a Location dashboard filter to your SQL question. In this example, you'd create a new dashboard (or go to an existing dashboard), click the **Pencil icon** to enter **Dashboard edit mode**, add the SQL question that contains your State Field Filter variable, add a new dashboard filter (or edit an existing Location filter), then click the dropdown on the SQL question card to see the State Field Filter.
 
 If you add a **Date** variable to the question, then it's only possible to use the dashboard filter option **Single Date**. So if you are trying to use one of the other Time options on the dashboard, you'll need to change the variable to a [Field Filter](#the-field-filter-variable-type) variable and map it to a date column.
 

docs/troubleshooting-guide/error-message.md

@@ -10,7 +10,7 @@ An error message can help you find the right troubleshooting guide. The exact wo
 
 See if your error details contain any of:
 
-- [Table or column not found](https://www.metabase.com/learn/debugging-sql/sql-syntax.html#column-or-table-name-is-not-found-or-not-recognized).
+- [Table or column "not found" or "not recognized"](https://www.metabase.com/learn/debugging-sql/sql-syntax.html#column-or-table-name-is-not-found-or-not-recognized).
 - [Function does not exist](https://www.metabase.com/learn/debugging-sql/sql-syntax.html#sql-function-does-not-exist).
 - [Permission denied](./data-permissions.md#getting-a-permission-denied-error-message).
 

docs/troubleshooting-guide/filters.md

@@ -74,7 +74,7 @@ Timestamps, in particular, are the root of all evil, so please be patient with y
 ## Related topics
 
 - [Troubleshooting linked filters](./linked-filters.md)
-- [Troubleshooting SQL variables](./sql.md#sql-variables-and-field-filters)
+- [Troubleshooting SQL variables and field filters](./sql.md#sql-variables-and-field-filters)
 - [Troubleshooting dates and times](./timezones.md)
 - [Creating dropdown filters](../data-modeling/metadata-editing.md#changing-a-search-box-filter-to-a-dropdown-filter)
 - [Creating SQL filters](../questions/native-editor/sql-parameters.md#the-field-filter-variable-type)

docs/troubleshooting-guide/sql.md

@@ -15,7 +15,7 @@ title: Troubleshooting SQL questions
 ## SQL variables and field filters
 
 - [Filter widget doesn't display a dropdown menu of values](../data-modeling/metadata-editing.md#changing-a-search-box-filter-to-a-dropdown-filter).
-- [SQL query contains a subquery (nested query) or CTE](../questions/native-editor/sql-parameters.md#field-filters-dont-work-with-table-aliases).
+- [SQL query contains table aliases](../questions/native-editor/sql-parameters.md#table-aliases).
 - [SQL syntax error: missing `FROM` clause](../questions/native-editor/sql-parameters.md#include-dependencies-in-your-query).
 - [No option to display a filter widget](../questions/native-editor/sql-parameters.md#field-filter-compatible-types).
 - [I don't know the SQL variable type](https://www.metabase.com/learn/sql-questions/sql-variables#the-different-types-of-variables-available-for-native-sql-queries).