The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs: metrics (#71778)
Alex Yarosha63333ac045b
diff --git a/docs/data-modeling/images/entity-picker-metrics-tab.png b/docs/data-modeling/images/entity-picker-metrics-tab.pngdeleted file mode 100644index d71e3e03d6c..00000000000Binary files a/docs/data-modeling/images/entity-picker-metrics-tab.png and /dev/null differdiff --git a/docs/data-modeling/images/formula.png b/docs/data-modeling/images/formula.pngindex 0f02f4868c1..d2110bdeeb6 100644Binary files a/docs/data-modeling/images/formula.png and b/docs/data-modeling/images/formula.png differdiff --git a/docs/data-modeling/images/metric-definition.png b/docs/data-modeling/images/metric-definition.pngnew file mode 100644index 00000000000..c21bf9eeb92Binary files /dev/null and b/docs/data-modeling/images/metric-definition.png differdiff --git a/docs/data-modeling/images/metric-explorer.png b/docs/data-modeling/images/metric-explorer.pngnew file mode 100644index 00000000000..ff6361bc173Binary files /dev/null and b/docs/data-modeling/images/metric-explorer.png differdiff --git a/docs/data-modeling/images/metric.png b/docs/data-modeling/images/metric.pngnew file mode 100644index 00000000000..a3a77f19e36Binary files /dev/null and b/docs/data-modeling/images/metric.png differdiff --git a/docs/data-modeling/images/metrics-built-on-other-metrics.png b/docs/data-modeling/images/metrics-built-on-other-metrics.pngdeleted file mode 100644index 2ef4114f12a..00000000000Binary files a/docs/data-modeling/images/metrics-built-on-other-metrics.png and /dev/null differdiff --git a/docs/data-modeling/images/use-metric-in-qb.png b/docs/data-modeling/images/use-metric-in-qb.pngnew file mode 100644index 00000000000..3fefc30cff7Binary files /dev/null and b/docs/data-modeling/images/use-metric-in-qb.png differdiff --git a/docs/data-modeling/metrics.md b/docs/data-modeling/metrics.mdindex 4ef4bb009ee..28eae712de7 100644--- a/docs/data-modeling/metrics.md+++ b/docs/data-modeling/metrics.md@@ -3,62 +3,121 @@ title: Metricsredirect_from:- /docs/latest/administration-guide/07-segments-and-metrics- /docs/latest/data-modeling/segments-and-metrics+summary: Metrics are reusable, standardized aggregations that let your team consistently define important numbers across your Metabase.---# Metrics-Create metrics to define the official way to calculate important numbers for your team.+Metrics define the official way to calculate important numbers for your team.++Metrics are like pre-defined calculations: create your aggregations once, save them as metrics, and use them whenever you need to analyze your data.For example, you may want to create a metric that calculates revenue, so people can refer to revenue in their own questions. That way you standardize how revenue is calculated (so you don't end up with five different calculations for the revenue).-## Metrics in the query builder+## How metrics work++Think of a metric like a reusable formula. For example, you can create a metric on a `Survey` table that calculates `(CountIf([Score] >= 9) - CountIf([Score] <= 6)) / Count()` (a.k.a. Net Promoter Score). Now other people in your Metabase, instead of writing their own version of NPS, can simply look up that agreed-upon NPS metric, or refer to it in the [query builder](../questions/query-builder/editor.md) when creating new questions.++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.++Metabase will show the metrics as an option in the query builder along with the basic aggregations like Count or Sum.-When asking questions in the query builder, you can find metrics that your team created in the summarization section under **Common metrics**. You can pick multiple metrics and they will be calculated independently and joined automatically along the chosen dimensions.+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).++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.++## Use metrics in the query builder++When you start a question on a [data source that has a metric defined](#metric-data-sources), Metabase will show you metrics on that data source in the **Summarize** block under **Metrics**.+Custom metrics work just like built-in metrics (Count, Sum etc): you can break out metrics by dimensions, include multiple metrics, and refer to metrics in custom expressions.+++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.-+## 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.++To create a metric:++1. Bring up the command palette with cmd/ctrl + k (that’s cmd + k for Macs, or ctrl + k for Windows PCs) and search for **New metric**++ You can also create a new metric by going to **Browse > Metrics** in the navigation sidebar and clicking on **+**.++ If you're creating a [Library metric](../data-studio/library.md#metrics), you can also [navigate to the Library](../data-studio/library.md) and click **+ New > 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.-You can use custom expressions to combine multiple metrics, or perform calculations on top of metrics.+3. Define your metric. The metric editor is similar to the regular query builder, with two key differences:-## Using metrics+ - 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).-You can:+ -- When creating questions in the query builder, you can pick metrics as aggregation columns in the Summarize block. You can modify metrics, or combine them.-- Save metrics to [collections](../exploration-and-organization/collections.md), including the [Library](../data-studio/library.md).-- Add metrics to [dashboards](../dashboards/introduction.md).-- View metrics in the [database browser](../exploration-and-organization/exploration.md#browse-your-databases).-- [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans include the ability to [mark metrics as verified](../exploration-and-organization/content-verification.md).+ 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.-## Creating a metric+4. Click **Save**. Metrics live in collections, so you'll need to pick a collection for the metric to save.-To create a metric, bring up the command palette with cmd/ctrl + k. That’s cmd + k for Macs, or ctrl + k for Windows PCs. Search for New metric.+## Edit a metric-You can also create a new metric by going to **Browse > Metrics** in the navigation side bar and clicking on **+**.+To edit a metric:-Select your starting data. You can start from a model, metric, table, or saved question.+1. Navigate to the metric you want to edit.-The metric editor is similar to the regular query builder, with two key differences:+ You can visit metric in its collection, find it in the [metrics browser](#see-all-metrics), or search for it.-- The aggregation section is called [**Formula**](#metric-formula)-- The group by section is called the [**Default time dimension**](#metric-default-time-dimension). You can only group by a single time dimension.+2. To edit the metric's definition, switch to the **Definition tab**.-+ -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.+ If you edit metric's definition, all questions that use the metric will immediately start using the new definition.++3. Save your changes.++## Explore and compare metrics++You can explore metrics, break them out by different dimensions, and compare metrics and [measures](../data-studio/data-structure.md#measures) to each other in the [Metrics Explorer](../questions/metrics-explorer.md).++++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).++You can build metrics on tables, saved questions, models, and other metrics.++We don't recommend using joins in metric definitions. If you need to build a metric that uses information from multiple tables, consider making a [transform](../data-studio/transforms/transforms-overview.md) to join those tables, _then_ create a metric on the table the transform creates.## Metric formulaThe formula is the core of the metric. It's the thing you are aggregating, and it's required when defining a metric.-You can build metrics on top of existing metrics.+You can use [custom expressions](../questions/query-builder/expressions.md) to define a metric, for example:++```+ (CountIf([Score] >= 9) - CountIf([Score] <= 6) ) / Count() * 100+```++Metric formula must to be an _aggregation_ of a column, meaning you can have a formula like `Sum([Price])` which will add up all the values in the `Price` column across all records, but you can't have a formula like `[Price] + [Tax]` which adds two values on a per-record basis. If you need to create a "calculated" column, consider using [transforms](../data-studio/transforms/transforms-overview.md) or [models](../data-modeling/models.md) instead.++We don't recommend adding filters into the metric definition to avoid filter conflicts when using metrics in the query builder. You can use conditional custom expressions like [`CountIf`, `SumIf`, and `DistinctIf`](../questions/query-builder/expressions-list.md#aggregations) to create conditional aggregations.-+You can reference other metrics when defining the formula for your metric.## Metric default time dimension@@ -70,31 +129,44 @@ Setting a time dimension doesn't lock the metric to that specific dimension. IfFor 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.-## Editing a metric+## See all metrics-To edit a metric, click on the three dot menu (**...**) and select **Edit metric definition**. Editing a metric requires curate access to the metric's collection.+You can see all metrics on your instance:-Do your thing, and save your changes.--When you click on a metric, Metabase will assume that you're using that metric as the starting point for a new question. You can save any changes you make as a new question, but these changes won't affect the metric's definition.+- Open the left navigation sidebar and select **Metrics** under **Data**.+- Alternatively, bring up the command palette with cmd/ctrl + k (that’s cmd + k for Macs, or ctrl + k for Windows PCs) and search for **Browse metrics**.## Metric permissions-Like questions, models, and dashboards, whether a group can view or edit a metric depends on [collection permissions](../permissions/collections.md). By "view" we mean the ability to see the metric in a collection, or see the metric as an option when building a query with the metric's data source. If a metric is used in another question, whether a group can view the question depends on the question's collection, not the metric's collection.+Because metrics live in collections, are attached to a data source, and define a query, permissions for metrics are determined by a combination of [collection permissions](../permissions/collections.md), ["View data" permissions](../permissions/data.md#can-view-data-permission), and ["Create queries" permissions](../permissions/data.md#create-queries-permissions).-By "editing" a metric, we mean [editing the metric's query definition](#editing-a-metric).+| Metric action \ Permissions | View data | Create queries | Collection |+| --------------------------------- | ------------- | ------------------------ | ---------- |+| **Create** or **edit** definition | Not "Blocked" | At least "Query builder" | Curate |+| **View** | Not "Blocked" | Any | View |+| **Use** in the query builder | Not "Blocked" | At least "Query builder" | View |-These collection permissions also interact with the group's [data permissions](../permissions/data.md), which define whether the group can view or query the metric's source data.+Anyone who has these permissions will be able to interact with the metric: for example, anyone with curate permissions to a collection, and "Create queries" permission on a data source will be able to create metrics in the collection that they can curate.## Metrics in the Library-By adding metrics to your Library, the query builder will display the metrics more prominently in menus. See [Library metrics](../data-studio/library.md#metrics)+By adding metrics to your Library, the query builder will display the metrics more prominently in menus. See [Library metrics](../data-studio/library.md#metrics).## Verifying a metric-See [content verification](../exploration-and-organization/content-verification.md). Prefer using [Library metrics](../data-studio/library.md#metrics) instead of content verification.+On [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans, you can [mark metrics as verified](../exploration-and-organization/content-verification.md).++Prefer using the [Library](../data-studio/library.md#metrics) to let people know which metrics they should use.++## Limitations++- For now, metrics are associated with a specific data source, and can't be used on any other data source, including on data sources derived from metric's original data source.+- Metrics are only available to the query builder. For defining reusable bits of SQL, check out [Snippets](../questions/native-editor/snippets.md).+- You can't limit people from creating metrics on data sources they otherwise have permissions to query.## Further reading+- [Measures](../data-studio/data-structure.md#measures)- [Models](./models.md)- [Segments](./segments.md)+- [SQL Snippets](../questions/native-editor/snippets.md)diff --git a/docs/data-studio/data-structure.md b/docs/data-studio/data-structure.mdindex 589a239cbe9..a7f61ef93e6 100644--- a/docs/data-studio/data-structure.md+++ b/docs/data-studio/data-structure.md@@ -50,7 +50,6 @@ See [Publishing tables](./library.md#publishing-tables) in the [Library docs](./## Sync settings-You can trigger manual re-sync of the table schema. Re-syncing can be useful if you have added or removed columns from the table, and you don't see those changes reflected in Metabase.You can also re-scan field values for the table or discard cached field values, which is useful if you need to retrieve updated values for dropdown filters.@@ -153,3 +152,7 @@ Deleting a measure will not break questions using it. The questions that use the1. Select the table in **Data structure**.2. Scroll down and switch to **Measures** and choose your measure.3. On the measure's page, click on the **three dots** icon next to the measure's name and select **Remove measure**.++### Explore a measure++You can explore measures along dimensions and compare measures and measures in the [Metrics Explorer](../questions/metrics-explorer.md).diff --git a/docs/questions/images/break-out-metric.png b/docs/questions/images/break-out-metric.pngnew file mode 100644index 00000000000..effc2c2528bBinary files /dev/null and b/docs/questions/images/break-out-metric.png differdiff --git a/docs/questions/images/breakout-chart-explorer.png b/docs/questions/images/breakout-chart-explorer.pngnew file mode 100644index 00000000000..45afe8f4027Binary files /dev/null and b/docs/questions/images/breakout-chart-explorer.png differdiff --git a/docs/questions/images/compare-metrics.png b/docs/questions/images/compare-metrics.pngnew file mode 100644index 00000000000..795b12c3f88Binary files /dev/null and b/docs/questions/images/compare-metrics.png differdiff --git a/docs/questions/images/filtered-metric.png b/docs/questions/images/filtered-metric.pngnew file mode 100644index 00000000000..59ab595e805Binary files /dev/null and b/docs/questions/images/filtered-metric.png differdiff --git a/docs/questions/images/metrics-explorer.png b/docs/questions/images/metrics-explorer.pngnew file mode 100644index 00000000000..ff6361bc173Binary files /dev/null and b/docs/questions/images/metrics-explorer.png differdiff --git a/docs/questions/images/pick-first-dimension.png b/docs/questions/images/pick-first-dimension.pngnew file mode 100644index 00000000000..8eefd980860Binary files /dev/null and b/docs/questions/images/pick-first-dimension.png differdiff --git a/docs/questions/images/pick-second-dimension.png b/docs/questions/images/pick-second-dimension.pngnew file mode 100644index 00000000000..5aad97b77a2Binary files /dev/null and b/docs/questions/images/pick-second-dimension.png differdiff --git a/docs/questions/images/two-metrics.png b/docs/questions/images/two-metrics.pngnew file mode 100644index 00000000000..b067e6d9b4cBinary files /dev/null and b/docs/questions/images/two-metrics.png differdiff --git a/docs/questions/metrics-explorer.md b/docs/questions/metrics-explorer.mdnew file mode 100644index 00000000000..fac185f515d--- /dev/null+++ b/docs/questions/metrics-explorer.md@@ -0,0 +1,91 @@+---+title: Metrics explorer+summary: Explore metrics and measures across dimensions and compare them side by side.+---++# Metrics explorer++The metrics Explorer is a space for ad-hoc analysis of [metrics](../data-modeling/metrics.md) and [measures](../data-studio/data-structure.md#measures)++++The metrics explorer can help you visualize trends and breakdowns of different metrics and measures from one or more data sources. For example, you might want to see how the revenue trend compares to changes in customer sentiment for different products.++You can:++- [Explore metrics and measures along their dimensions](#explore-a-metric-or-a-measure)+- [Compare multiple metrics and measures](#compare-metrics-and-measures)+- [Break out by additional dimensions](#break-out-by-dimensions)+- [Filter each metric or measure](#filter-metrics-and-measures)+- Zoom into time periods++The metric explorer is intended for ad hoc exploration and analysis. Currently, you can't save the results of your explorations. You can use the [query builder](../questions/query-builder/editor.md) to create saved explorations.++To share your metric explorations with people in your organization, you can copy the link (which will look like `[your-metabase-URL]/explore#abunchofcharacters`). The link encodes your explorations, so other people will be able to see what you see.++## Explore a metric or a measure++To open a **metric** in the Metrics Explorer:++1. Navigate to the metric's home page.++ To get to the metric's home page, you can click on a metric from its collection, from the [metrics browser](../data-modeling/metrics.md#see-all-metrics), or from search.++2. Click **Explore** in the top right corner to open the metrics explorer++To get back to the metric's page from metrics explorer, right-click the metric card in the search bar and select **Go to metric home page**.++To open a **measure** in the metrics explorer, go directly to `[your metabase URL]/explore` and type the measure's name in the search bar. To get back to the measure definition from metrics explorer, right-click the measure card in the search bar and select **Edit in Data Studio**.++## Compare metrics and measures++To compare multiple metrics or measures, search for measure or metric you want to add in the search bar.++++You'll see the dimensions of the first metric/measure below the search bar. You can pick a dimension to break out the metrics/measures (for example, if you want to see how both Number of Orders and Revenue change by date, state, or product category).++++Metabase will automatically detect shared dimensions and offer them for comparison, like when the metrics/measures are associated with the same data source, or the underlying data sources have foreign key relationships to another shared data source.++If your metrics/measures don't have shared dimensions, you'll need to select a dimension for comparison:++1. Click on the **+** under the search bar to select a dimension for the first metric/measure.++ ++2. At the bottom of the screen, select compatible dimensions for other metrics/measures.++ ++When your metrics/measures don't have shared dimensions, Metabase has no way of knowing how the dimensions relate to each other, so it's on you to make sure the dimensions you pick make sense to compare!++## Break out by dimensions++You can also break out each metric by additional dimensions. For example, you might want to compare overall revenue to the number of orders for each product category.++To break out a metric or measure by additional dimensions:++1. Right-click on the metric's card in the search bar.+2. Select **Break out**+ +3. Choose the breakout dimension.++++To remove the breakout, right-click on the measure/metric card again and select **Remove breakout**++## Filter metrics and measures++You can add filters to each metric/measure in the metrics explorer. For example, you might want to compare overall revenue trend to number of orders for one specific product category.++To add a filter to a metric or measure:++1. Click the **filter** icon in the top right corner of the metrics explorer.+2. Select the metric/measure you want to filter.+3. Select the field to filter and define the filter.++You'll see the filter added below the metric or measure's card in the search bar. To remove the filter, click the **X** on the filter's card.++diff --git a/docs/questions/start.md b/docs/questions/start.mdindex b8bc8f56fab..385dac48d3e 100644--- a/docs/questions/start.md+++ b/docs/questions/start.md@@ -70,6 +70,10 @@ Use saved questions as data sources in your native queries.Reuse and share bits of SQL.+## [Metrics Explorer](./metrics-explorer.md)++Explore metrics and measures across dimensions, compare them side by side, and drill into the data — without building a question from scratch.+## Sharing resultsThere are many different ways to share the results of questions. To share the results of a dashboard, see [Dashboard subscriptions](../dashboards/subscriptions.md).