From b742af5183fcc16c35ffd13ac3523ebde41ef016 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 17 Jul 2024 09:14:03 +0100 Subject: [PATCH] update measures doc (#5737) this pr updates some yaml code exmaples in the measure doc. raised by Zach in dbt community slack: https://getdbt.slack.com/archives/C02CCBBBR1D/p1719959209705599 Outstanding question raised to SL team: - Can non_additive_dimensions be used with all metric types? (probably a harder question) --- website/docs/docs/build/join-logic.md | 21 +++++++-------- website/docs/docs/build/measures.md | 37 ++++++++++++++------------- 2 files changed, 30 insertions(+), 28 deletions(-) diff --git a/website/docs/docs/build/join-logic.md b/website/docs/docs/build/join-logic.md index f83fd063f05..cf4c1608284 100644 --- a/website/docs/docs/build/join-logic.md +++ b/website/docs/docs/build/join-logic.md @@ -43,9 +43,9 @@ MetricFlow primarily uses left joins for joins, and restricts the use of fan-out ### Example -The following example uses two semantic models with a common entity and shows a MetricFlow query that requires a join between the two semantic models. - -Let's say you have two semantic models, `transactions` and `user_signup` as seen in the following example: +The following example uses two semantic models with a common entity and shows a MetricFlow query that requires a join between the two semantic models. The two semantic models are: +- `transactions` +- `user_signup` ```yaml semantic_models: @@ -70,16 +70,17 @@ semantic_models: type: categorical ``` -MetricFlow will use `user_id` as the join key to join two semantic models, `transactions` and `user_signup`. This enables you to query the `average_purchase_price` metric in `transactions`, sliced by the `type` dimension in the `user_signup` semantic model. - -Note that the `average_purchase_price` measure is defined in the `transactions` semantic model, where `user_id` is a foreign entity. However, the `user_signup` semantic model has `user_id` as a primary entity. - -Since this is a foreign-to-primary relationship, a left join is implemented where the `transactions` semantic model joins the `user_signup` semantic model since the `average_purchase_price` measure is defined in the `transactions` semantic model. +- MetricFlow uses `user_id` as the join key to link two semantic models, `transactions` and `user_signup`. This allows you to query the `average_purchase_price` metric in the `transactions` semantic model, grouped by the `type` dimension in the `user_signup` semantic model. + - Note that the `average_purchase_price` measure is defined in `transactions`, where `user_id` is a foreign entity. However, `user_signup` has `user_id` as a primary entity. +- Since `user_id` is a foreign key in `transactions` and a primary key in `user_signup`, MetricFlow performs a left join where `transactions` joins `user_signup` to access the `average_purchase_price` measure defined in `transactions`. +- To query dimensions from different semantic models, add a double underscore (or dunder) to the dimension name after joining the entity in your editing tool. The following query, `user_id__type` is included as a dimension using the `--group-by` flag (`type` is the dimension). -When querying dimensions from different semantic models using the CLI, a double underscore (or dunder) is added to the dimension name after the joining entity. In the CLI query shown below, `user_id__type` is included as a `dimension`. +```yaml +dbt sl query --metrics average_purchase_price --group-by metric_time,user_id__type # In dbt Cloud +``` ```yaml -mf query --metrics average_purchase_price --dimensions metric_time,user_id__type +mf query --metrics average_purchase_price --group-by metric_time,user_id__type # In dbt Core ``` ## Multi-hop joins diff --git a/website/docs/docs/build/measures.md b/website/docs/docs/build/measures.md index 3c548f20c8c..5e0772f517e 100644 --- a/website/docs/docs/build/measures.md +++ b/website/docs/docs/build/measures.md @@ -6,7 +6,7 @@ sidebar_label: "Measures" tags: [Metrics, Semantic Layer] --- -Measures are aggregations performed on columns in your model. They can be used as final metrics or serve as building blocks for more complex metrics. +Measures are aggregations performed on columns in your model. They can be used as final metrics or as building blocks for more complex metrics. Measures have several inputs, which are described in the following table along with their field types. @@ -31,7 +31,7 @@ measures: ### Name -When you create a measure, you can either give it a custom name or use the `name` of the data platform column directly. If the `name` of the measure is different from the column name, you need to add an `expr` to specify the column name. The `name` of the measure is used when creating a metric. +When you create a measure, you can either give it a custom name or use the `name` of the data platform column directly. If the measure's `name` differs from the column name, you need to add an `expr` to specify the column name. The `name` of the measure is used when creating a metric. Measure names must be unique across all semantic models in a project and can not be the same as an existing `entity` or `dimension` within that same model. @@ -88,7 +88,7 @@ If the `name` you specified for a measure doesn't match a column name in your mo **Notes**: When using SQL functions in the `expr` parameter, **always use data platform-specific SQL**. This is because outputs may differ depending on your specific data platform. :::tip For Snowflake users -For Snowflake users, if you use a week-level function in the `expr` parameter, it'll now return Monday as the default week start day based on ISO standards. If you have any account or session level overrides for the `WEEK_START` parameter that fix it to a value other than 0 or 1, you will still see Monday as the week start. +For Snowflake users, if you use a week-level function in the `expr` parameter, it'll now return Monday as the default week start day based on ISO standards. If you have any account or session level overrides for the `WEEK_START` parameter that fixes it to a value other than 0 or 1, you will still see Monday as the week starts. If you use the `dayofweek` function in the `expr` parameter with the legacy Snowflake default of `WEEK_START = 0`, it will now return ISO-standard values of 1 (Monday) through 7 (Sunday) instead of Snowflake's legacy default values of 0 (Monday) through 6 (Sunday). ::: @@ -200,7 +200,7 @@ Parameters under the `non_additive_dimension` will specify dimensions that the m ```yaml semantic_models: - - name: subscription_table + - name: subscription_id description: A subscription table with one row per date for each active user and their subscription plans. model: ref('your_schema.subscription_table') defaults: @@ -209,6 +209,7 @@ semantic_models: entities: - name: user_id type: foreign + primary_entity: subscription_table dimensions: - name: metric_time @@ -218,22 +219,22 @@ semantic_models: time_granularity: day measures: - - name: count_users_end_of_month + - name: count_users description: Count of users at the end of the month - expr: 1 - agg: sum + expr: user_id + agg: count_distinct non_additive_dimension: name: metric_time - window_choice: min - - name: mrr_end_of_month - description: Aggregate by summing all users' active subscription plans at the end of month + window_choice: max + - name: mrr + description: Aggregate by summing all users' active subscription plans expr: subscription_value agg: sum non_additive_dimension: name: metric_time window_choice: max - - name: mrr_by_user_end_of_month - description: Group by user_id to achieve each user's MRR at the end of the month + - name: mrr + description: Group by user_id to achieve each user's MRR expr: subscription_value agg: sum non_additive_dimension: @@ -243,10 +244,10 @@ semantic_models: - user_id metrics: - - name: mrr_end_of_month + - name: mrr_metrics type: simple type_params: - measure: mrr_end_of_month + measure: mrr ``` We can query the semi-additive metrics using the following syntax: @@ -254,15 +255,15 @@ We can query the semi-additive metrics using the following syntax: For dbt Cloud: ```bash -dbt sl query --metrics mrr_by_end_of_month --dimensions metric_time__month --order metric_time__month -dbt sl query --metrics mrr_by_end_of_month --dimensions metric_time__week --order metric_time__week +dbt sl query --metrics mrr_by_end_of_month --group-by metric_time__month --order metric_time__month +dbt sl query --metrics mrr_by_end_of_month --group-by metric_time__week --order metric_time__week ``` For dbt Core: ```bash -mf query --metrics mrr_by_end_of_month --dimensions metric_time__month --order metric_time__month -mf query --metrics mrr_by_end_of_month --dimensions metric_time__week --order metric_time__week +mf query --metrics mrr_by_end_of_month --group-by metric_time__month --order metric_time__month +mf query --metrics mrr_by_end_of_month --group-by metric_time__week --order metric_time__week ``` import SetUpPages from '/snippets/_metrics-dependencies.md';