docs - saved question page - closes #14198

docs/users-guide/08-dashboard-filters.md

@@ -118,6 +118,8 @@ To link filters, you'll need to set up this parent-child relationship. And you s
 
 Here you can limit the current filter's choices. If you toggle on one of these dashboard filters, selecting a value for that filter will limit the available choices for this filter. In this case, we toggle on the state filter (the parent), to limit the choices for the city filter. When states are selected, the city filter will limit its choices to cities in those states. Click **Done**, then **Save** to save the dashboard.
 
+To learn more, check out [Linking filters in dashboards](https://www.metabase.com/learn/building-analytics/dashboards/linking-filters.html).
+
 ### Best practices
 
 Here are a few tips to get the most out of dashboard filters:

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

@@ -161,33 +161,8 @@ WHERE True
   [[AND {% raw %}{{category}}{% endraw %}]]
 ```
 
-### Using an existing question as a sub-query
-
-You can use an existing question in a new query with the following variable syntax:
-
-```
-SELECT count(*)
-FROM {% raw %}{{#123}}{% endraw %}
-```
-
-This will return the number of records returned by the existing question with ID 123. A question's ID is the number at the end of the URL in your browser's location bar, after `/question/`, when viewing the question.
-
-Alternatively, you can select the target question in the sidebar, in the "Question #..." box that appears after typing `{% raw %}{{#}}{% endraw %}` in the query editor. 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.
-
-The same syntax can be used in Common Table Expressions (CTEs), with databases that support them:
-
-```
-WITH filtered_products AS {% raw %}{{#123}}{% endraw %}
-SELECT count(*)
-FROM filtered_products
-```
-
-The `{% raw %}{{#123}}{% endraw %}` tag is substituted for the SQL query of the referenced question, surrounded by parentheses.
-
-**Note:** Sub-queries are only supported in SQL databases.
-
 ---
 
-## Next: automated x-ray explorations
+## Next: Referencing saved questions in queries
 
-Learn about how to easily and quickly see automatic explorations of your data with Metabase's powerful [x-ray feature](14-x-rays.md).
+Learn how to [refer to a saved question in a SQL query](referencing-saved-questions-in-queries.md).

docs/users-guide/interactive-dashboards.md

@@ -31,7 +31,6 @@ SQL questions will only have the option to **Go to a custom destination**, and *
 
 If your dashboard has a filter, you'll also see an option to [update the filter](#use-a-chart-to-filter-a-dashboard).
 
-
 ### Open the action menu
 
 For questions composed using the query builder, the default click behavior is to open the **action menu**, which presents people with the option to [drill through the data](https://www.metabase.com/blog/drilling-through-data/index.html):
@@ -86,6 +85,8 @@ For example, we could type a URL like this:
 
 Next we’ll click **Done**, then **Save** our dashboard. Now when we click our chart, we’ll be taken to the URL that we entered above, with the value of the clicked bar inserted into the URL.
 
+To learn more, check out [Custom destinations: choose what happens when people click on charts in your dashboard](https://www.metabase.com/learn/building-analytics/dashboards/custom-destinations.html).
+
 ### Use a chart to filter a dashboard
 
 If your dashboard contains at least one filter, you can set things up so that clicking on a chart in the dashboard will update a filter.
@@ -112,6 +113,8 @@ Click **Done** in the sidebar, then **Save** your dashboard.
 
 Now we can use our navigation question (Orders by product category) to interactively filter the data across your dashboard. When people click on a value in the navigation question, Metabase will send the clicked value to the filter, and update every card on the dashboard by filtering them for the clicked value - every card except for the navigation question: Orders by product category. The reason we don't want the navigation question to update is so that we can click on other bars to update the filter with a different value.
 
+To learn more, check out [Cross-filtering: using a chart to update a dashboard filter](https://www.metabase.com/learn/building-analytics/dashboards/cross-filtering.html).
+
 ---
 
 ## Next: Charts with multiple series

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

+## Referencing saved questions in queries
+
+With SQL databases, we can use an existing question as the basis for a new query, or as a common table expression (CTE). For example, let's say we have a lot of data spread across a number of tables, but our users are most interested in a subset of that data. We can perform a complicated query once to return those results, which people can refer to in their queries just like they would with any other table.
+
+Here's how it works. First, create and save a question that returns the result set you'd like to make available for people to query. Using the sample dataset included with Metabase as an example, let's say we want to provide a result set (a "table") that only has orders from 2019, and only includes orders for products in the Gizmo category.
+
+We could create this question using the notebook editor, like so:
+
+![Example notebook](images/saved-questions/example-notebook.png).
+
+Alternatively, we could create that question using SQL:
+
+```
+SELECT *
+FROM   orders AS o
+       INNER JOIN products AS p
+               ON o.product_id = p.id
+WHERE  p.category = 'Gizmo'
+       AND o.created_at BETWEEN '2019-01-01' AND '2019-12-31'
+```
+
+We'll save that question as "Gizmo orders in 2019".
+
+Now let's refer to "Gizmo orders in 2019" in a new query. To keep it simple, let's say we just want to count all of those Gizmo orders from 2019. We can use the `#` symbol to refer to a saved question in a query.
+
+If we type out:
+
+```
+SELECT count(*)
+FROM {% raw %}{{#{% endraw %}
+```
+
+Metabase will slide out a sidebar where we can select a question to reference. We'll search for our "Gizmo orders in 2019" question:
+
+![Select a question from the variable sidebar](images/saved-questions/variable-sidebar.png)
+
+We'll select that question, and Metabase will update our code with the question's ID, `5`:
+
+```
+SELECT count(*)
+FROM {% raw %}{{#5}}{% endraw %}
+```
+
+This query returns the number of rows in our saved question.
+
+## Saved question as a Common Table Expression (CTE)
+
+The same syntax can be used in [Common Table Expressions (CTEs)](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression) (with SQL databases that support CTEs):
+
+```
+WITH 2019_gizmo_orders AS {% raw %}{{#5}}{% endraw %}
+SELECT count(*)
+FROM 2019_gizmo_orders
+```
+
+When this query is run, the `{% raw %}{{#5}}{% endraw %}` tag will be substituted with the SQL query of the referenced question, surrounded by parentheses. So it'll look like this under the hood:
+
+```
+WITH 2019_gizmo_orders AS (SELECT *
+FROM   orders AS o
+       INNER JOIN products AS p
+               ON o.product_id = p.id
+WHERE  p.category = 'Gizmo'
+       AND o.created_at BETWEEN '2019-01-01' AND '2019-12-31')
+SELECT count(*)
+FROM 2019_gizmo_orders
+```
+
+# How to find a question's ID
+
+- Selecting a question from the variable sidebar in the SQL editor will automatically add the ID number to the variable in our query.
+- You can also navigate to the question you'd like to reference and find its ID at the end of the URL in your browser's address bar, after `/question/`. E.g., for `https://metabase.example.com/question/12345`, the question's ID would be `12345`.
+
+## When and why to use saved questions as a data source
+
+- If you can't create a view in the database, since saved questions effectively act as views. If you can create a view, and you expect that you and others will frequently query the results, consider creating a materialized view. The results will be stored in the database (as opposed to computed each time), which will speed up query time.
+- To simplify or standardize queries for people. If you have data split across multiple tables, you can perform those complicated joins once, and provide the results as a simplified "table" that people can query.
+
+For other ways to standardize analytics, check out:
+
+- [Segments and Metrics](../administration-guide/07-segments-and-metrics.md)
+- [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)
+
+### Limitations and tradeoffs
+
+- You can only reference a saved question in a query when working with a SQL database like PostgreSQL, MySQL, or SQL Server.
+- 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.
+
+---
+
+## Next: automated X-ray explorations
+
+Learn about how to easily and quickly see automatic explorations of your data with Metabase's powerful [X-ray feature](14-x-rays.md).

docs/users-guide/sql-snippets.md

@@ -93,4 +93,7 @@ Any user who has SQL editor permissions to at least one of your connected databa
 
 ### Learn more
 
-Learn more about [SQL snippets](https://www.metabase.com/blog/sql-snippets/index.html).
\ No newline at end of file
+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).

docs/users-guide/start.md

@@ -29,6 +29,7 @@
 - [Referencing your data model while writing SQL](12-data-model-reference.md)
 - [Creating SQL Templates](13-sql-parameters.md)
 - [Using SQL snippets to reuse and share code](sql-snippets.md)
+- [Referencing saved question in queries](referencing-saved-questions-in-queries.md)
 - [Getting automatic insights with X-rays](14-x-rays.md)
 - [Setting and getting alerts](15-alerts.md)