docs - troubleshooting sql, error messages, and sql error messages

docs/troubleshooting-guide/error-message.md

+# Different types of error messages
+- [API error messages][api-error-message]
+- [SQL error messages][sql-error-message]
+- [Metabase error messages][metabase-error-message]
+
+## [API error messages][discourse-search-api-error]
+
+- Appear in red text when you load a dashboard or run a question.
+- Contain a three-digit API error code, such as `400` or `404`.
+- If your error message contains part of your SQL query, go to SQL error messages below.
+
+
+## [SQL error messages][troubleshoot-sql]
+
+- Appear in red text when you run a question that uses the [SQL editor][sql-editor].
+- Contain part of your SQL query, such as a column or table name.
+- May also contain a three-digit API error code, such as `400` or `404`.
+
+
+## [Metabase error messages][discourse-search-metabase-error]
+
+- Appear in gray text when you load a dashboard or run a question.
+
+
+[api-error-message]: #api-error-messages
+[discourse-search-api-error]: https://discourse.metabase.com/search?q=api%20error%20message
+[discourse-search-metabase-error]: https://discourse.metabase.com/search?q=metabase%20error%20message
+[metabase-error-message]: #metabase-error-messages
+[sql-error-message]: #sql-error-messages
+[troubleshoot-sql]: ./sql-error-message.html
+[sql-editor]: /glossary/native_query_editor.html

docs/troubleshooting-guide/filters.md

@@ -8,6 +8,8 @@ You've tried to add a [filter widget][filter-widget-gloss] to your dashboard, bu
 
 If you've created a [linked filter][linked-filter-gloss], please see [this troubleshooting guide][troubleshoot-linked-filters] instead.
 
+If you're using a [SQL variable][sql-variable-gloss] with the variable type "field filter", go to [Troubleshooting SQL variables][troubleshoot-sql-variables].
+
 ## Is the dashboard filter actually connected to your question?
 
 **Root cause:** The filter isn't connected to any cards on the dashboard, or connected to the wrong field.
@@ -24,7 +26,8 @@ If you've created a [linked filter][linked-filter-gloss], please see [this troub
 
 **Steps to take**:
 
-1. Check that your SQL query contains at least [one variable][sql-variable] for the filter to insert the value. These can be plain variables, or [Field Filters][field-filter], with names enclosed in double curly braces `{% raw %}{{variable_name}}{% endraw %}`, typically in a `WHERE` clause.
+1. Check that your SQL query contains at least [one variable][sql-variable-gloss] for the filter to insert the value. These can be plain variables, or [Field Filters][field-filter], with names enclosed in double curly braces `{% raw %}{{variable_name}}{% endraw %}`, typically in a `WHERE` clause.
+2. If these steps don’t fix your error, go to [Troubleshooting SQL variables][troubleshoot-sql-variables].
 
 If you built your question in the Query Builder, Metabase knows which columns you're using, and which columns you can connect to different types of filters. So you can add a dashboard filter and refer to columns in the question's results without creating variables explicitly.
 
@@ -59,6 +62,7 @@ If a filter that used to work no longer seems to, or seems to eliminate all of t
 [field-filter]: /learn/sql-questions/field-filters.html
 [filter-widget-gloss]: /glossary/filter_widget
 [linked-filter-gloss]: /glossary/linked_filter
-[sql-variable]: /learn/sql-questions/sql-variables.html
+[sql-variable-gloss]: /glossary/variable#example-variable-in-metabase
 [sync-scan]: ./sync-fingerprint-scan.html
 [troubleshoot-linked-filters]: ./linked-filters.html
+[troubleshoot-sql-variables]: ./sql.html#my-sql-variables-arent-working

docs/troubleshooting-guide/index.md

@@ -33,6 +33,7 @@ Problems, their causes, how to detect them, and how to fix them.
 
 - [Saving questions or dashboards][proxies].
 - [My dashboard is slow][slow-dashboard].
+- [My SQL question doesn't work][sql].
 - [The dates and times in my questions and charts are wrong][incorrect-times].
 - [My dashboard filters don't work][filters].
 - [My dashboard's linked filters don't work][linked-filters].
@@ -41,6 +42,10 @@ Problems, their causes, how to detect them, and how to fix them.
 
 - [Metabase isn't sending email][not-sending-email].
 
+### Error messages
+
+- [I'm getting an error message][error-message].
+
 ## Think you found a bug?
 
 Let us know by [filing a bug report][bugs].
@@ -82,6 +87,7 @@ Metabase adds new features and squashes bugs with each release. [Upgrading to th
 [datawarehouse]: ./datawarehouse.html
 [docker]: ./docker.html
 [edge]: https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium
+[error-message]: error-message.html
 [feature-request]: requesting-new-features.html
 [filters]: ./filters.html
 [firefox]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console
@@ -101,5 +107,6 @@ Metabase adds new features and squashes bugs with each release. [Upgrading to th
 [saml]: ./saml.md
 [sandbox]: ./sandboxing.html
 [slow-dashboard]: ./my-dashboard-is-slow.html
+[sql]: ./sql.html
 [sync-fingerprint-scan]: ./sync-fingerprint-scan.html
 [upgrade]: ../operations-guide/upgrading-metabase.html

docs/troubleshooting-guide/sql-error-message.md

+## What's wrong with your SQL query?
+
+- [I get an error message that mentions part of my SQL query][sql-debugging].
+- [I get an error message that isn't specific to my SQL query][troubleshoot-error-messages].
+- [I don't have an error message, but my query results are incorrect][troubleshoot-sql-logic].
+
+## Debugging SQL queries
+
+If your SQL query contains [SQL variables][sql-variable-def] that look like `{% raw %}{{ variable }}{% endraw %}`, go to [Troubleshooting SQL variables][troubleshoot-sql-variables] first.
+
+1. Go to the line that is failing in your SQL query.
+   - [I don’t know where my SQL query is failing][how-to-find-failing-sql-line].
+2. Check the [SQL syntax][troubleshoot-sql-syntax] on the line that is failing in your SQL query.
+3. Check your [query logic][troubleshoot-sql-logic] if the query uses joins, subqueries, or CTEs.
+4. If you get an error message that isn't specific to your SQL query, go to [Troubleshooting error messages][troubleshoot-error-messages].
+
+### How does SQL debugging work?
+
+- SQL error messages are displayed for each line in your query that fails to run. You'll need to follow the steps above for each line that failed.
+- If you make any changes to a line, run your query to check if the problem is fixed before moving on to the next step. You can add a `LIMIT` clause at the end of your query to speed up the process.
+- Note that [SQL queries are not run from top to bottom][sql-order-execution], so you won’t be debugging your query lines in the order that they are written. Follow the error messages to help you find the lines that need attention.
+
+## Troubleshooting SQL syntax errors
+
+1. Review the spelling on the line that is failing in your SQL query.
+2. Review for missing brackets or commas on the line that is failing in your SQL query.
+3. Remove commented lines (lines that begin with `--` or `/*`).
+4. Review for common syntax errors that are [specific to your SQL dialect][sql-reference-guide].
+
+### Common SQL reference guides
+
+Before you start, open up the SQL reference guide for the SQL dialect that you’re using. We’ve linked to some of the most common ones here:
+
+- [MySQL](https://dev.mysql.com/doc/refman/8.0/en/language-structure.html)
+- [PostgreSQL](https://www.postgresql.org/docs/current/sql-syntax-lexical.html)
+- [Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/t-sql/language-reference)
+- [Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/dg/cm_chap_SQLCommandRef.html)
+- [Google BigQuery](https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical)
+- [Snowflake](https://docs.snowflake.com/en/sql-reference/constructs.html)
+- [I don’t know what SQL dialect to use][how-to-find-sql-dialect].
+
+### Common SQL syntax errors
+
+What does your error message say?
+
+- [My column or table name is "not found" or "not recognized"][sql-error-not-found].
+- [My SQL "function does not exist”][sql-error-function-does-not-exist].
+
+If you have a different error message, search or ask the [Metabase community][discourse].
+
+#### My column or table name is "not found" or "not recognized"
+
+If your SQL query contains [SQL variables][sql-variable-def] that look like `{% raw %}{{ variable }}{% endraw %}`, go to [Troubleshooting SQL variables][troubleshoot-sql-variables] first.
+
+**Steps**
+
+1.  Review the **structure** section of the [reference guide][sql-reference-guide] for your SQL dialect.
+
+    - Are you using the correct quotation marks? For example:
+
+      - `SELECT 'column_name'`
+      - `SELECT "column_name"`
+      - ``SELECT `column_name` ``
+
+    - Are you using the correct path to columns and tables? For example:
+
+      - `FROM table_name`
+      - `FROM schema_name.table_name`
+      - `FROM database_name.schema_name.table_name`
+
+    - Is your column name a reserved word? For example:
+
+      [In PostgresSQL, 'users' is a reserved key word](https://www.postgresql.org/docs/current/sql-keywords-appendix.html).
+
+      - `SELECT users` will throw an error.
+      - `SELECT "users"` will run correctly.
+    
+    - **Tip: Use Metabase to check for column and table name syntax**
+
+      1. Create a simple question in the [notebook editor][notebook-editor] using the same columns and tables as your SQL question.
+      2. [Convert the question to SQL][how-to-convert-gui-question-to-sql].
+      3. Look at how the Metabase-generated SQL query refers to column and table names.
+
+2.  Review the [data reference][data-reference] for the column and table names in your query.
+
+    - If the column or table name doesn't exist in the data reference:
+      - Run `SELECT * FROM your_table_name LIMIT 10;` to look for the column or table name to use in your query.
+      - If you're a Metabase admin, check the Data model page for the [original schema][original-schema].
+
+    - If the column name exists, but you can’t query the column from the SQL editor: 
+      - Ask your Metabase admin if the column was re-named or removed on the database side.
+      - If you’re a Metabase admin, you may need to [run a sync][database-syncing] to refresh your data.
+
+3.  If you no longer have an error message, but your query results are incorrect, go to [Troubleshooting SQL logic][troubleshoot-sql-logic].
+4.  If you get an error message that isn't specific to your SQL query, go to [Troubleshooting error messages][troubleshoot-error-messages].
+5.  If you're still stuck, search or ask the [Metabase community][discourse].
+
+**Explanation**
+
+You need to make sure that you're using the correct syntax for the SQL dialect used by your database. 
+
+Your query also needs to use column and table names that match the original names in your database. Metabase uses [display names][column-metadata] that can be updated by your Metabase admin, so the data reference may not match your database schema. It's also possible that a column or table was re-named on the database side, but Metabase hasn’t run a sync to grab the updates.
+
+**Further reading**
+
+- [How Metabase executes SQL queries][how-metabase-executes-queries].
+- [How Metabase syncs with your database][database-syncing].
+
+#### My SQL "function does not exist”
+
+If your SQL query contains [SQL variables][sql-variable-def] that look like `{% raw %}{{ variable }}{% endraw %}`, go to [Troubleshooting SQL variables][troubleshoot-sql-variables] first.
+
+**Steps**
+
+1. Review the data type of the column that you want your function to apply to.
+
+   - You can use the Metabase [data reference][data-reference] to review the column's [field type][field-type-def] (as a proxy for [data type][data-type-def]).
+   - You can also directly query the information schema in your database if you have permission to access it.
+
+2. Review the **function** section of the [reference guide][sql-reference-guide] for your SQL dialect.
+
+   - Confirm that the function exists for your SQL dialect.
+   - Review the data type(s) that are accepted by your function.
+
+3. If the field type of your column does not match the expected data type of your function:
+
+   - Cast your column to the correct data type in your SQL query.
+   - If you’re a Metabase admin, you can also [cast data types from the Data model page][how-to-cast-data-type].
+
+4. If you no longer have an error message, but your query results are incorrect, go to [Troubleshooting SQL logic][troubleshoot-sql-logic].
+5. If you get an error message that isn't specific to your SQL query, go to [Troubleshooting error messages][troubleshoot-error-messages].
+6. If you're still stuck, search or ask the [Metabase community][discourse].
+
+**Explanation**
+
+SQL functions are designed to work on specific data types in your database. For example, the [`DATE_TRUNC` function in PostgresSQL](https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC) works on columns with `date`, `timestamp`, and `time` typed data in a Postgres database. If you try to use the `DATE_TRUNC` function on a column with a `string` data type in your database, it won’t work. 
+
+Note that Metabase [field types][field-type-def] are not one-to-one with the data types in your database. In this case, the field type gives you enough information about the column data type to troubleshoot the error.
+
+**Further reading**
+
+- [How Metabase executes SQL queries][how-metabase-executes-queries].
+- [Field types documentation][field-type-doc].
+
+## I don’t know which line of my SQL query is failing
+
+If your SQL query contains [SQL variables][sql-variable-def] that look like `{% raw %}{{ variable }}{% endraw %}`, go to [Troubleshooting SQL variables][troubleshoot-sql-variables] first.
+
+Once you find the line that is failing in your SQL query, go to the [Debugging SQL][sql-debugging] steps.
+
+### Reading your SQL error message
+
+Does your error message:
+- Tell you the line or character position?
+- Include a table or column name? If the table or column name appears more than once in your query, [reduce the size of your query][how-to-reduce-sql-query-size].
+- Mention a SQL clause?
+
+### Reducing the size of a SQL query
+
+If your query uses:
+
+- **Subqueries** (nested queries), run each subquery separately. Start with the inner subqueries and work your way out.
+- **CTEs**, run each CTE separately. Start with your base CTE and work your way down the query.
+- **SQL variables that point to Metabase models**, run each model separately. Go to the model by opening the variables panel, or enter the model ID number from the variable in the Metabase search bar.
+- Remember to [read the SQL error message][how-to-read-sql-error] as you try to isolate the problem. For more information, go to [How does SQL debugging work?][how-does-sql-debugging-work].
+
+**Tips for working in the Metabase SQL editor**
+
+Highlight lines of your SQL query to:
+- Run the lines with `Cmd + Return` or `Ctrl + Enter`.
+- Comment/uncomment the lines with  `Cmd + /` or `Ctrl + /`.
+
+## I don’t know what SQL dialect to use
+
+The SQL dialect is based on the [database][data-source-list] that stores the tables you want to query. Once you find out what SQL dialect to use, you can follow the [Debugging SQL][sql-debugging] steps.
+
+To find out which database you’re querying:
+
+- If you’re a Metabase admin, go to **Admin > Databases,** and look under the **Engine** column.
+- Otherwise, ask the person who set up your Metabase.
+
+## Are you still stuck?
+
+Search or ask the [Metabase community][discourse].
+
+[column-metadata]: ../administration-guide/03-metadata-editing.html#metadata-for-columns
+[data-reference]: ../users-guide/12-data-model-reference.html
+[data-source-list]: https://www.metabase.com/datasources/
+[database-syncing]: ../administration-guide/01-managing-databases.html#database-syncing
+[data-type-def]: /glossary/data_type.html
+[discourse]: https://discourse.metabase.com/search?q=sql%20error%20message
+[field-type-def]: /glossary/field_type.html
+[field-type-doc]: ../users-guide/field-types.html
+[how-metabase-executes-queries]: ../users-guide/writing-sql.html#how-metabase-executes-sql-queries
+[how-to-cast-data-type]: ../administration-guide/03-metadata-editing#casting-to-a-specific-data-type 
+[how-to-convert-gui-question-to-sql]: ../users-guide/04-asking-questions.html#viewing-the-sql-that-powers-your-question
+[how-does-sql-debugging-work]: #how-does-sql-debugging-work
+[how-to-find-failing-sql-line]: #i-dont-know-which-line-of-my-sql-query-is-failing
+[how-to-find-sql-dialect]: #i-dont-know-what-sql-dialect-to-use
+[how-to-read-sql-error]: #reading-your-sql-error-message
+[how-to-reduce-sql-query-size]: #reducing-the-size-of-a-sql-query
+[notebook-editor]: ../users-guide/04-asking-questions.html#the-query-builder
+[original-schema]: ../administration-guide/03-metadata-editing.html#original-schema
+[sql-debugging]: #debugging-sql-queries
+[sql-error-function-does-not-exist]: #my-sql-function-does-not-exist
+[sql-error-message]: ./sql-error-message.html
+[sql-error-not-found]: #my-column-or-table-name-is-not-found-or-not-recognized
+[sql-editor]: /glossary/native_query_editor.html
+[sql-order-execution]: /learn/sql-questions/sql-best-practices.html#the-general-order-of-query-execution
+[sql-reference-guide]: #common-sql-reference-guides
+[sql-variable-def]: /glossary/variable.html#example-variable-in-metabase
+[troubleshoot-error-messages]: ./error-message.html
+[troubleshoot-sql-logic]: ./sql.html#my-sql-query-results-are-incorrect
+[troubleshoot-sql-syntax]: #troubleshooting-sql-syntax-errors
+[troubleshoot-sql-variables]: ./sql.html#my-sql-variables-arent-working
\ No newline at end of file

docs/troubleshooting-guide/sql.md

+# Troubleshooting SQL questions
+
+## [I'm getting a SQL error message][sql-error-message]
+
+- The error message appears in red text when you run a question that uses the [SQL editor][sql-editor].
+- The error message contains part of your SQL query, such as a column or table name.
+- The error message may also contain a three-digit API error code, such as `400` or `404`.
+
+## My SQL query results are incorrect
+
+- [My query uses joins](/learn/sql-questions/sql-join-types.html#common-problems-with-sql-joins).
+- [My dates and times are wrong](/docs/latest/troubleshooting-guide/timezones.html).
+
+## My SQL variables aren't working
+
+What type of [SQL variable][sql-variable-def] are you using?
+
+### Field filter variables
+
+- [My filter widget doesn't display a dropdown menu of values](./filters.html#are-you-seeing-a-different-kind-of-input-widget-than-you-expected).
+- [My SQL query contains a subquery (nested query) or CTE](../users-guide/13-sql-parameters.html#field-filters-dont-work-with-table-aliases).
+- [I'm getting a 400 error from BigQuery](../users-guide/13-sql-parameters.html#some-databases-require-the-schema-in-the-from-clause).
+
+### Text, number, or date variables
+
+- [I don't see the option to display a filter widget](../users-guide/13-sql-parameters.html#field-filter-compatible-types).
+
+### I don't know the variable type
+
+- [Visit Metabase Learn to read about the different types of SQL variables][sql-variable-type].
+
+## Are you still stuck?
+
+If you can’t solve your problem using the troubleshooting guides, search or ask the [Metabase community][discourse].
+
+[discourse]: https://discourse.metabase.com/
+[sql-editor]: /glossary/native_query_editor.html
+[sql-error-message]: ./sql-error-message.html
+[sql-variable-def]: /glossary/variable.html#example-variable-in-metabase
+[sql-variable-type]: /learn/sql-questions/sql-variables.html#the-different-types-of-variables-available-for-native-sql-queries
\ No newline at end of file

docs/users-guide/13-sql-parameters.md

@@ -263,6 +263,7 @@ More on [Dashboard filters][dashboard-filters].
 
 - [Create filter widgets for charts using SQL variables][sql-variables].
 - [Field Filters: create smart filter widgets for SQL questions][field-filter].
+- [Troubleshooting SQL][troubleshooting-sql].
 - [Troubleshooting filters][troubleshooting-filters].
 - [Dashboard filters][dashboard-filters].
 
@@ -279,4 +280,5 @@ Learn how to [refer to a saved question in a SQL query](referencing-saved-questi
 [filtering-on-this-field]: ../administration-guide/03-metadata-editing.html#picking-the-filter-user-interface-for-a-column
 [sql-variables]: /learn/sql-questions/sql-variables.html
 [troubleshooting-filters]: ../troubleshooting-guide/filters.html
+[troubleshooting-sql]: ../troubleshooting-guide/sql.html
 [basic-input]: /learn/sql-questions/sql-variables.html#basic-input-variable-text

docs/users-guide/referencing-saved-questions-in-queries.md

@@ -90,6 +90,10 @@ For other ways to standardize analytics, check out:
 - The saved question you select has to be one that's based on the same database as the one you've currently selected in the native query editor.
 - You cannot reference variables in sub-queries. You only have access to the _results_ of the saved question, not the saved question's query. For example, if you have a saved question that uses a [field filter](https://www.metabase.com/learn/building-analytics/sql-templates/field-filters), you won't be able to reference that variable. If you need to change how the saved question has filtered the results, you'll need to update (or duplicate) that question and apply the filter.
 
+## Need help?
+
+If you're having trouble with your SQL query, go to the [SQL troubleshooting guide](../troubleshooting-guide/sql.html).
+
 ---
 
 ## Next: automated X-ray explorations

docs/users-guide/sql-snippets.md

@@ -97,3 +97,4 @@ Check out:
 
 - [SQL snippets](https://www.metabase.com/learn/building-analytics/sql-templates/sql-snippets.html)
 - [SQL Snippets vs Saved Questions vs Views](https://www.metabase.com/learn/building-analytics/sql-templates/organizing-sql.html).
+- If you're having trouble with your SQL query, go to the [SQL troubleshooting guide](../troubleshooting-guide/sql.html).

docs/users-guide/writing-sql.md

@@ -52,6 +52,10 @@ You can use [SQL snippets](sql-snippets.md) to save, reuse, and share SQL code a
 
 - [Best practices for writing SQL queries](https://www.metabase.com/learn/sql-questions/sql-best-practices.html)
 
+## Need help?
+
+If you're having trouble with your SQL query, go to the [SQL troubleshooting guide][troubleshoot-sql].
+
 ---
 
 ## Next: Creating charts