Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - sql table variable (#69817)

Jeff Bruemmerd2f7234d7faa
diff --git a/docs/README.md b/docs/README.md
index 0853496f127..0d9c8e3f143 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -87,6 +87,7 @@ Metabase's reference documentation.
- [The SQL editor](./questions/native-editor/writing-sql.md)
- [SQL parameters](./questions/native-editor/sql-parameters.md)
+- [Table variables](./questions/native-editor/table-variables.md)
- [Referencing models and saved questions](./questions/native-editor/referencing-saved-questions-in-queries.md)
- [Snippets](./questions/native-editor/snippets.md)
- [Snippet folder permissions](./permissions/snippets.md)
diff --git a/docs/questions/images/table-variable.png b/docs/questions/images/table-variable.png
new file mode 100644
index 00000000000..9afaa7b8630
Binary files /dev/null and b/docs/questions/images/table-variable.png differ
diff --git a/docs/questions/native-editor/snippets.md b/docs/questions/native-editor/snippets.md
index a2eea686578..b1613077520 100644
--- a/docs/questions/native-editor/snippets.md
+++ b/docs/questions/native-editor/snippets.md
@@ -140,6 +140,8 @@ When a snippet with parameters is added to a SQL query, Metabase will show a wid
You'll be able to specify the type, connected columns, and default values for the parameters coming from snippets in the query's Variables sidebar.
+## Values for snippet parameters are defined by the question, not the snippet
+
Settings for snippet parameters are defined by the query, not the snippet, so settings aren't shared between queries that use the same snippet. For example, if you have a snippet like:
```sql
@@ -150,9 +152,24 @@ you could put the snippet in one query and have the snippet parameter map to a `
If you have multiple snippets containing parameters with the same name, the question using those snippets will only use one instance of the parameter. For example, if `{% raw %}{{snippet: 1}}{% endraw %}` contains parameter `{% raw %}{{var}}{% endraw %}` and `{% raw %}{{snippet: 2}}{% endraw %}` also contains parameter `{% raw %}{{var}}{% endraw %}`, the question will display only one `{% raw %}{{var}}{% endraw %}` parameter and use its value in both snippets.
+### Table variables in snippets
+
+You can also use [table variables](./table-variables.md) in snippets to write a generic query once and reuse it across different tables, inserting a new table in each question.
+
+```sql
+{% raw %}
+SELECT
+ COUNT(*)
+FROM
+ {{table}}
+{% endraw %}
+```
+
### Sharing parameters across questions
-You can also use snippets to share parameters across multiple SQL questions, including questions that build on one another (nested questions). For example, you have a question “Orders by date” that filters orders using `{% raw %}{{start_date}}{% endraw %}`. You then create another question, say “Revenue by product,” that uses the results from “Orders by date.” To keep using the same `{% raw %}{{start_date}}{% endraw %}` parameter in both questions, move the SQL that contains the parameter from “Orders by date” into a snippet and update both questions to reference that snippet. Now, both questions surface the same parameter, and a single dashboard date filter can control both cards that use the snippet.
+You can also use snippets to share parameters across multiple SQL questions, including questions that build on one another (nested questions).
+
+For example, you have a question “Orders by date” that filters orders using `{% raw %}{{start_date}}{% endraw %}`. You then create another question, say “Revenue by product,” that uses the results from “Orders by date.” To keep using the same `{% raw %}{{start_date}}{% endraw %}` parameter in both questions, move the SQL that contains the parameter from “Orders by date” into a snippet and update both questions to reference that snippet. Now, both questions surface the same parameter, and a single dashboard date filter can control both cards that use the snippet.
## Snippet permissions
diff --git a/docs/questions/native-editor/sql-parameters.md b/docs/questions/native-editor/sql-parameters.md
index 216e46dac07..491e6150669 100644
--- a/docs/questions/native-editor/sql-parameters.md
+++ b/docs/questions/native-editor/sql-parameters.md
@@ -22,6 +22,7 @@ Variable types include:
- **[Field filter variables](./field-filters.md)**: create "smart" filter widgets with date pickers or dropdown menus. To use a field filter, you'll need to connect to a database field included in your query.
- **[Basic variables](./basic-sql-parameters.md)**: text, number, and date variables. You'll almost always want to use field filters instead of these basic variables, as field filters create "smart" filter widgets, but Metabase provides these basic variables for situations where you can't use field filters.
- **[Time grouping parameters](./time-grouping-parameters.md)**: allows people to change how the results are grouped by a date column: by month, week, day, etc.
+- **[Table variables](./table-variables.md)**: select which table to query. Pretty nifty when combined with [snippets](./snippets.md).
You can include multiple variables in a single query, and Metabase will add multiple widgets to the question. To rearrange the order of the widgets, enter edit mode and click on any widget and drag it around.
diff --git a/docs/questions/native-editor/table-variables.md b/docs/questions/native-editor/table-variables.md
new file mode 100644
index 00000000000..43cf91371ae
--- /dev/null
+++ b/docs/questions/native-editor/table-variables.md
@@ -0,0 +1,88 @@
+---
+title: Table variables
+summary: Table variables let you dynamically select which database table to query in the SQL editor.
+---
+
+# Table variables
+
+![Table variables](../images/table-variable.png)
+
+Table variables let you write a SQL query with a placeholder for the table name. When you run the query, Metabase substitutes the variable with the schema and table name.
+
+Table variables are especially useful when combined with [snippets](./snippets.md), so you can write a generic query once and reuse it across different tables.
+
+## Adding a table variable to a query
+
+Use double braces where you'd normally write a table name:
+
+```sql
+{% raw %}
+SELECT
+ COUNT(*)
+FROM
+ {{table}}
+{% endraw %}
+```
+
+You can use table variables anywhere a table name would go, including `FROM` and `JOIN` clauses:
+
+```sql
+{% raw %}
+SELECT
+ t.*,
+ p.title
+FROM
+ {{table}} AS t
+ JOIN {{products_table}} AS p ON t.product_id = p.id
+{% endraw %}
+```
+
+Metabase inserts the table reference using the schema-qualified name (e.g., `public.orders`), so some databases like PostgreSQL will require you to use an alias. For example: `SELECT t.id FROM {% raw %}{{table}}{% endraw %} t`.
+
+### Setting the variable type to Table
+
+After adding a `{% raw %}{{variable}}{% endraw %}` to your query:
+
+1. Open the **Variables** sidebar (it should appear automatically).
+2. Change the variable type to **Table**.
+3. Under **Table to map to**, select a table from the picker (Required).
+
+When you run the query, Metabase replaces the variable with the selected table's schema and table name. To preview the code Metabase will run, click the **eye** icon.
+
+## Using table variables with snippets
+
+One neat thing you can do is combine table variables with [snippets](./snippets.md). You can write a generic query as a snippet and reuse the snippet in multiple questions, each mapped to a different table.
+
+For example, create a snippet called "row count" with:
+
+```sql
+{% raw %}
+SELECT
+ COUNT(*)
+FROM
+ {{table}}
+{% endraw %}
+```
+
+Then insert the snippet into different questions:
+
+```sql
+{% raw %}
+{{snippet: row count}}
+{% endraw %}
+```
+
+In each question, open the Variables sidebar and map `{% raw %}{{table}}{% endraw %}` to a different database table. This way, the same snippet can count rows in `Products`, `Orders`, or any other table.
+
+## Limitations
+
+- **Not available as dashboard filter parameters.** You can't connect a table variable to a dashboard filter widget. Table variables must be set directly on each question.
+- **SQL queries only.** Table variables are available in native SQL queries, not in the query builder.
+- **No input widget.** There's no input widget for people to plug in a table. You must select the table to insert into the variable from the variables sidebar.
+- **Not supported in transforms.** Table variables aren't available in [transforms](../../data-studio/transforms/transforms-overview.md) yet.
+
+## Further reading
+
+- [SQL parameters](./sql-parameters.md)
+- [Snippets](./snippets.md)
+- [SQL troubleshooting guide](../../troubleshooting-guide/sql.md)