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

@@ -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

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,26 +244,26 @@ 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:
 
 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';