Skip to content

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

docs: add metric dimensions page (#79772)

Michael Eby4ba5c162e5d4
diff --git a/docs/data-modeling/images/formula.png b/docs/data-modeling/images/formula.png
index d2110bdeeb6..27b6df30220 100644
Binary files a/docs/data-modeling/images/formula.png and b/docs/data-modeling/images/formula.png differ
diff --git a/docs/data-modeling/images/metric-dimensions.png b/docs/data-modeling/images/metric-dimensions.png
new file mode 100644
index 00000000000..fa7c2224729
Binary files /dev/null and b/docs/data-modeling/images/metric-dimensions.png differ
diff --git a/docs/data-modeling/images/metric.png b/docs/data-modeling/images/metric.png
index f2cca408ae8..ef0da7fa5a0 100644
Binary files a/docs/data-modeling/images/metric.png and b/docs/data-modeling/images/metric.png differ
diff --git a/docs/data-modeling/images/pinned-metrics.png b/docs/data-modeling/images/pinned-metrics.png
deleted file mode 100644
index 70b4de70589..00000000000
Binary files a/docs/data-modeling/images/pinned-metrics.png and /dev/null differ
diff --git a/docs/data-modeling/metrics.md b/docs/data-modeling/metrics.md
index c79b81188ec..8fac32158d8 100644
--- a/docs/data-modeling/metrics.md
+++ b/docs/data-modeling/metrics.md
@@ -24,11 +24,11 @@ Metrics have three components:
- [**Data source**](#metric-data-sources): metrics are associated with a specific data source and can be used in any question built on that data source.
- [**Formula**](#metric-formula): the aggregation's definition.
-- [**Optional default time dimension**](#metric-default-time-dimension): a default time dimension to be used when displaying the metric as a standalone card on a dashboard or a pinned item in the collection. This time dimension doesn't affect how the metric is computed.
+- [**Dimensions**](#metric-dimensions): the fields people can use to break out and filter the metric, including an optional default dimension Metabase uses to display it.
Metabase will show the metrics as an option in the query builder along with the basic aggregations like Count or Sum.
-If you use a metric as you aggregation, Metabase will replace the metric with the saved formula behind the scenes. See [Use metrics in the query builder](#use-metrics-in-the-query-builder).
+If you use a metric as your aggregation, Metabase will replace the metric with the saved formula behind the scenes. See [Use metrics in the query builder](#use-metrics-in-the-query-builder).
Metrics live in collections. You can save metrics into the [Library](../data-studio/library.md) collection to surface your org's official curated metrics and encourage people to use them for their own questions.
@@ -42,11 +42,11 @@ Custom metrics work just like built-in metrics (Count, Sum etc): you can break o
![Metric built on top of other metrics](./images/use-metric-in-qb.png)
-You can also pick a metric as a data source when creating a new question. If the metric has a time dimension, Metabase will include the time dimension as a grouping. You can change the groupings to break out the metric by other dimensions.
+You can also pick a metric as a data source when creating a new question. Metabase adds the metric in the **Summarize** step, and you can group the results by any column from the metric's source data.
## Create a metric
-A metric consists of three parts: the data source, the formula that defines how a metric is computed, and an optional time dimension.
+A metric consists of three parts: the data source, the formula that defines how a metric is computed, and its dimensions.
To create a metric:
@@ -58,19 +58,20 @@ To create a metric:
2. Select your starting data. You can start from a table, saved question, model, or another metric.
- Metric will be usable only on the data source you defined it on.
+ A metric will be usable only on the data source you defined it on.
-3. Define your metric. The metric editor is similar to the regular query builder, with two key differences:
+3. Define your metric. The metric editor is similar to the regular query builder, with one key difference:
- The [**Formula**](#metric-formula) block is where you define your aggregation. You can use [custom expressions](../questions/query-builder/expressions.md) to write the formula, for example `SumIf([Total], [Plan] != 'free')`.
- - The [**Default time dimension**](#metric-default-time-dimension) is where you can optionally include a default way for Metabase to group the metric by time when displaying the metric on a dashboard, document, or collection card. This time dimension isn't used for computing the metric (you can specify any other dimension when actually using the metric).
![Formula](./images/formula.png)
- Only the data and formula steps are required to define a metric. You can join and filter data before the formula step, and set a default time dimension to group by.
+ Only the data and formula steps are required to define a metric. You can join and filter data before the formula step.
4. Click **Save**. Metrics live in collections, so you'll need to pick a collection for the metric to save.
+ After saving, you can curate the metric's [dimensions](#metric-dimensions) on the **Dimensions** tab.
+
## Edit a metric
To edit a metric:
@@ -89,15 +90,15 @@ To edit a metric:
## Explore, compare, and do math with metrics
-To break metrics out by different dimensions, compare metrics and [measures](../data-studio/measures.md), and do math with metrics (like add or divide metrics by each other), check out the [Metrics Explorer](../questions/metrics-explorer.md).
+To break metrics out by different dimensions, compare metrics and [measures](../data-studio/measures.md), and do math with metrics (like add or divide metrics by each other), check out the [Metrics explorer](../questions/metrics-explorer.md).
![Metrics explorer](./images/metric-explorer.png)
-To see a metric in the Metrics Explorer, visit the metric and click **Explore** in the top right corner. You can add more metrics, breakouts, and filters to compare metrics along different dimensions.
+To see a metric in the Metrics explorer, visit the metric and click **Explore** in the top right corner. You can add more metrics, breakouts, and filters to compare metrics along different dimensions.
## Metric data sources
-Metrics are attached to a specific data source. This means that if you define a "Net Promoter Score" metric on the `Survey` table, you will be able to use the metric in any question that is build on the `Survey` table, but _only_ in questions that are built on the `Survey` table (and not, for example, any model or saved question that itself uses the `Survey` table).
+Metrics are attached to a specific data source. This means that if you define a "Net Promoter Score" metric on the `Survey` table, you will be able to use the metric in any question that is built on the `Survey` table, but _only_ in questions that are built on the `Survey` table (and not, for example, any model or saved question that itself uses the `Survey` table).
You can build metrics on tables, saved questions, models, and other metrics.
@@ -119,15 +120,36 @@ We don't recommend adding filters into the metric definition to avoid filter con
You can reference other metrics when defining the formula for your metric.
-## Metric default time dimension
+## Metric dimensions
+
+Metric dimensions are the fields people can use to break out and filter a metric, like grouping revenue by month or product category.
+
+![Dimensions tab](./images/metric-dimensions.png)
+
+By default, every column from a metric's source data serves as a dimension. You can curate a metric's dimensions to choose which fields appear as breakout and filter options. You can also set the default dimension Metabase uses to display the metric.
+
+Metabase uses the curated dimensions as the breakout and filter options in the [Metrics explorer](../questions/metrics-explorer.md), on the metric's **About** tab, and for dashboard filters. A dashboard filter can connect to the curated dimensions that match the filter's type.
+
+Curated dimensions don't affect the [query builder](../questions/query-builder/editor.md)'s filter and summarize pickers. When someone uses a metric in a question, they can filter and summarize by any column from the metric's source data.
+
+### Curate a metric's dimensions
+
+From the metric's **Dimensions** tab, you can:
+
+- **Add dimensions**: Click **Available dimensions** and select fields from the source table, joined tables, or [related tables](#dimensions-from-related-tables).
+- **Remove dimensions**: Select the checkbox next to each dimension, then click the trash icon. Dashboard filters can't use a dimension you remove.
+- **Reorder dimensions**: Drag a dimension by its handle. Metabase lists dimensions in this order everywhere the metric appears.
+- **Rename a dimension**: Click the dimension and enter a new name in the **Display name** field. Renaming doesn't affect the underlying field or other metrics that use the field.
+- **Set a default dimension**: Click the dimension, then click **Set as default**. Metabase uses the default to display the metric. Without a default, the metric displays as a single number. To undo, click **Remove default**.
+- **Set a time grouping**: Click a time dimension and select a default grouping from the dropdown.
-You can optionally set a default time dimension for the metric. Metabase will use this default time dimension when the metric is opened or displayed on a card in a collection or dashboard. In the image below that shows two pinned metrics at the top of a collection, the left metric lacks a default time dimension, so Metabase displays the metric as a number chart. The right metric has a default time dimension, so Metabase displays it as a line chart.
+### Dimensions from related tables
-![Pinned metrics](./images/pinned-metrics.png)
+If the metric's source table has foreign keys, the **Available dimensions** list also includes fields from the related tables.
-Setting a time dimension doesn't lock the metric to that specific dimension. If someone uses the metric in a question or dashboard, they'll be able to group by other time dimensions and granularities as well.
+Metabase groups these fields under the name of the foreign key column, not the name of the related table. For example, if an `Orders` table has a `User ID` column pointing to a `People` table, the `People` fields appear in a group named **User**.
-For example, you could calculate revenue and set a default time dimension of `Created At` by month, but if someone added that metric to a dashboard, they could group revenue by a different time granularity (e.g., by quarter). This is just an FYI so that you don't name a metric "Monthly Revenue" and think that by setting a default time dimension to "month", Metabase will prevent people from slicing revenue by other time granularities.
+If a table links to the same related table through two different columns, Metabase creates groups named after each column. For example, if both a `Reporter ID` and an `Assignee ID` column point to a `Users` table, the `Users` fields appear under two groups: **Reporter** and **Assignee**.
## See all metrics
@@ -182,4 +204,4 @@ See [Query caching](../configuring-metabase/caching.md).
- [Measures](../data-studio/measures.md)
- [Models](./models.md)
- [Segments](./segments.md)
-- [SQL Snippets](../questions/native-editor/snippets.md)
+- [SQL Snippets](../questions/native-editor/snippets.md)
\ No newline at end of file
diff --git a/docs/questions/metrics-explorer.md b/docs/questions/metrics-explorer.md
index 772542d5cca..e5a03506b30 100644
--- a/docs/questions/metrics-explorer.md
+++ b/docs/questions/metrics-explorer.md
@@ -46,9 +46,9 @@ To open a **measure** in the metrics explorer:
When you open a measure or metric in the Metrics explorer, Metabase plots it along the most appropriate dimension. To change how the metric is broken out, click the current breakout dimension in the bottom controls to open the **Break out** sidebar.
-By default, the sidebar lists all available dimensions. The heading reads **Dimensions** when you select a single metric or measure, or **Shared dimensions** when you compare multiple metrics or measures.
+The sidebar lists the metric's or measure's [dimensions](../data-modeling/metrics.md#metric-dimensions), excluding primary key and foreign key dimensions. The heading reads **Dimensions** when you select a single metric or measure, or **Shared dimensions** when you [compare](#compare-metrics-and-measures) multiple metrics or measures.
-To break out by a column that isn't listed, click **See all**. This shows every column from the table the metric or measure is built on, and any related tables. To see the total result without any dimensions, select **No breakout**.
+To see the total result without any dimensions, select **No breakout**.
You can also [break out](#break-out-by-dimensions) a metric/measure by additional dimensions or [filter the metric/measure](#filter-metrics-and-measures).
@@ -82,7 +82,7 @@ Once you pick the metrics or measures, open the **Break out** sidebar to choose
- **Compare across different time or country columns.** If your metrics/measures have time or country dimensions, you can choose which column each metric/measure uses for the comparison, even if they're different columns. For example, you can compare Orders by their order date with Reviews by their review date. Click the slider icon next to **Time** or **Country** to choose a dimension for each metric/measure.
![Metrics explorer time bucket comparison](images/metrics-explorer-time-bucket-comparison.png)
-- **Other columns require an exact match.** The column appears as a comparison option under **Shared dimensions** only if both metrics/measures have it. To break out by a column that only one metric/measure has, click **See all** and select that column. Metabase applies the breakout to that metric/measure and disables the other.
+- **Other columns require an exact match.** The column appears as a comparison option under **Shared dimensions** only if both metrics/measures have it. To break out by a dimension that only one metric/measure has, click **See all** and select it.
![Compare metrics](./images/two-metrics.png)