Merge branch 'current' into joellabes-patch-1

website/docs/docs/build/conversion-metrics.md

@@ -21,7 +21,7 @@ The specification for conversion metrics is as follows:
 | `name` | The name of the metric. |  Required |
 | `description` | The description of the metric. | Optional |
 | `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion' | Required |
-| `label` | Displayed value in downstream tools. | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
 | `type_params` | Specific configurations for each metric type. |  Required |
 | `conversion_type_params` | Additional configuration specific to conversion metrics. | Required |
 | `entity` | The entity for each conversion event. | Required |

website/docs/docs/build/cumulative-metrics.md

@@ -15,7 +15,7 @@ This metric is common for calculating things like weekly active users, or month-
 | `name` | The name of the metric. | Required |
 | `description` | The description of the metric. | Optional |
 | `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required |
-| `label` | The value that will be displayed in downstream tools. | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
 | `type_params` | The type parameters of the metric. | Required |
 | `window` | The accumulation window, such as 1 month, 7 days, 1 year. This can't be used with `grain_to_date`. | Optional  |
 | `grain_to_date` | Sets the accumulation grain, such as month will accumulate data for one month. Then restart at the beginning of the next. This can't be used with `window`. | Optional |

website/docs/docs/build/derived-metrics.md

@@ -15,7 +15,7 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi
 | `name` | The name of the metric. | Required |
 | `description` | The description of the metric. | Optional |
 | `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required |
-| `label` | The value that will be displayed in downstream tools. | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
 | `type_params` | The type parameters of the metric. | Required |
 | `expr` | The derived expression. | Required |
 | `metrics` |  The list of metrics used in the derived metrics. | Required  |
@@ -49,7 +49,7 @@ metrics:
   - name: order_gross_profit
     description: Gross profit from each order.
     type: derived
-    label: Order Gross Profit
+    label: Order gross profit
     type_params:
       expr: revenue - cost
       metrics:
@@ -58,7 +58,7 @@ metrics:
         - name: order_cost
           alias: cost
   - name: food_order_gross_profit
-    label: Food Order Gross Profit  
+    label: Food order gross profit
     description: "The gross profit for each food order."
     type: derived
     type_params:
@@ -75,7 +75,7 @@ metrics:
   - name: order_total_growth_mom
     description: "Percentage growth of orders total completed to 1 month ago"
     type: derived
-    label: Order Total Growth % M/M
+    label: Order total growth % M/M
     type_params:
       expr: (order_total - order_total_prev_month)*100/order_total_prev_month
       metrics: 
@@ -115,7 +115,7 @@ You can query any granularity and offset window combination. The following examp
 - name: d7_booking_change
   description: Difference between bookings now and 7 days ago
   type: derived
-  label: d7 Bookings Change
+  label: d7 bookings change
   type_params:
     expr: bookings - bookings_7_days_ago
     metrics:

website/docs/docs/build/dimensions.md

@@ -17,24 +17,25 @@ Groups are defined within semantic models, alongside entities and measures, and
 
 All dimensions require a `name`, `type` and in some cases, an `expr` parameter. The `name` for your dimension must be unique to the semantic model and can not be the same as an existing `entity` or `measure` within that same model.
 
-
 | Parameter | Description | Type |
 | --------- | ----------- | ---- |
 | `name` |  Refers to the name of the group that will be visible to the user in downstream tools. It can also serve as an alias if the column name or SQL query reference is different and provided in the `expr` parameter. <br /><br /> Dimension names should be unique within a semantic model, but they can be non-unique across different models as MetricFlow uses [joins](/docs/build/join-logic) to identify the right dimension. | Required |
 | `type` | Specifies the type of group created in the semantic model. There are three types:<br /><br />- **Categorical**: Group rows in a table by categories like geography, color, and so on. <br />- **Time**: Point to a date field in the data platform. Must be of type TIMESTAMP or equivalent in the data platform engine. <br />- **Slowly-changing dimensions**: Analyze metrics over time and slice them by groups that change over time, like sales trends by a customer's country. | Required |
 | `type_params` | Specific type params such as if the time is primary or used as a partition | Required |
 | `description` | A clear description of the dimension | Optional |
 | `expr` | Defines the underlying column or SQL query for a dimension. If no `expr` is specified, MetricFlow will use the column with the same name as the group. You can use column name itself to input a SQL expression. | Optional |
+| `label` | A recommended string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`).  | Optional |
 
 Refer to the following for the complete specification for dimensions:
 
 ```yaml
 dimensions:
-  - name: name of the group that will be visible to the user in downstream tools
-    type: Categorical or Time
-    type_params: specific type params such as if the time is primary or used as a partition
-    description: same as always
-    expr: the column name or expression. If not provided the default is the dimension name
+  - name: Name of the group that will be visible to the user in downstream tools # Required
+    type: Categorical or Time # Required
+    label: Recommended adding a string that defines the display value in downstream tools. # Optional
+    type_params: Specific type params such as if the time is primary or used as a partition # Required
+    description: Same as always # Optional
+    expr: The column name or expression. If not provided the default is the dimension name # Optional
 ```
 
 Refer to the following example to see how dimensions are used in a semantic model:
@@ -56,6 +57,7 @@ semantic_models:
   dimensions:
     - name: metric_time
       type: time
+      label: "Date of transaction" # Recommend adding a label to define the value displayed in downstream tools
       expr: date_trunc('day', ts)
     - name: is_bulk_transaction
       type: categorical
@@ -99,7 +101,6 @@ dimensions:
 
 ### Time
 
-
 :::tip use datetime data type if using BigQuery
 To use BigQuery as your data platform, time dimensions columns need to be in the datetime data type. If they are stored in another type, you can cast them to datetime using the `expr` property. Time dimensions are used to group metrics by different levels of time, such as day, week, month, quarter, and year. MetricFlow supports these granularities, which can be specified using the `time_granularity` parameter.
 :::
@@ -142,12 +143,14 @@ mf query --metrics messages_per_month --group-by metric_time__year --order metri
 dimensions: 
   - name: created_at
     type: time
+    label: "Date of creation"
     expr: date_trunc('day', ts_created) #ts_created is the underlying column name from the table 
     is_partition: True 
     type_params:
       time_granularity: day
   - name: deleted_at
     type: time
+    label: "Date of deletion"
     expr: date_trunc('day', ts_deleted) #ts_deleted is the underlying column name from the table 
     is_partition: True 
     type_params:
@@ -177,12 +180,14 @@ Aggregation between metrics with different granularities is possible, with the S
 dimensions: 
   - name: created_at
     type: time
+    label: "Date of creation"
     expr: date_trunc('day', ts_created) #ts_created is the underlying column name from the table 
     is_partition: True 
     type_params:
       time_granularity: day
   - name: deleted_at
     type: time
+    label: "Date of deletion"
     expr: date_trunc('day', ts_deleted) #ts_deleted is the underlying column name from the table 
     is_partition: True 
     type_params:
@@ -265,13 +270,15 @@ semantic_models:
     dimensions:
       - name: tier_start
         type: time
+        label: "Start date of tier"
         expr: start_date
         type_params:
           time_granularity: day
           validity_params:
             is_start: True
       - name: tier_end 
         type: time
+        label: "End date of tier"
         expr: end_date
         type_params:
           time_granularity: day
@@ -329,6 +336,7 @@ semantic_models:
     dimensions:
       - name: metric_time
         type: time
+        label: "Date of transaction"
         is_partition: true
         type_params:
           time_granularity: day

website/docs/docs/build/environment-variables.md

@@ -36,7 +36,7 @@ To set environment variables at the project and environment level, click **Deplo
 
 You'll notice there is a `Project Default` column. This is a great place to set a value that will persist across your whole project, independent of where the code is run. We recommend setting this value when you want to supply a catch-all default or add a project-wide token or secret.
 
-To the right of the `Project Default` column are all your environments. Values set at the environment level take priority over the project level default value. This is where you can tell dbt Cloud to interpret an environment value differently in your Staging vs. Production environment, as example.
+To the right of the `Project Default` column are all your environments. Values set at the environment level take priority over the project-level default value. This is where you can tell dbt Cloud to interpret an environment value differently in your Staging vs. Production environment, as an example.
 
 <Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/Environment Variables/project-environment-view.png" title="Setting project level and environment level values"/>
 
@@ -98,6 +98,8 @@ dbt Cloud has a number of pre-defined variables built in. Variables are set auto
 
 **dbt Cloud IDE details**
 
+The following environment variable is set automatically for the dbt Cloud IDE:
+
 - `DBT_CLOUD_GIT_BRANCH`: Provides the development Git branch name in the [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud).
   - Available in dbt v 1.6 and later.
   - The variable changes when the branch is changed.
@@ -110,7 +112,7 @@ Use case &mdash; This is useful in cases where you want to dynamically use the G
 
 **dbt Cloud context**
 
-The following environment variables are set automatically for deployment runs, and their values cannot be changed.
+The following environment variables are set automatically for deployment runs:
 
 - `DBT_ENV`: This key is reserved for the dbt Cloud application and will always resolve to 'prod'
 

website/docs/docs/build/measures.md

@@ -27,16 +27,14 @@ measures:
     agg_params: 'specific aggregation properties such as a percentile'  ## Optional
     agg_time_dimension: The time field. Defaults to the default agg time dimension for the semantic model. ##  Optional
     non_additive_dimension: 'Use these configs when you need non-additive dimensions.' ## Optional
-    label: How the metric appears in project docs and downstream integrations. ## Required
 ```
 
-### Name 
+### 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. 
 
 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.
 
-
 ### Description
 
 The description describes the calculated measure. It's strongly recommended you create verbose and human-readable descriptions in this field.

website/docs/docs/build/metricflow-commands.md

@@ -84,6 +84,10 @@ You can use the `dbt sl` prefix before the command name to execute them in the d
 - [`tutorial`](#tutorial) — Dedicated MetricFlow tutorial to help get you started.
 -->
 
+:::tip Run dbt parse to reflect metric changes
+When you make changes to metrics, make sure to run `dbt parse` at a minimum to update the dbt Semantic Layer. This updates the `semantic_manifest.json` file, reflecting your changes when querying metrics. By running `dbt parse`, you won't need to rebuild all the models.
+::: 
+
 <expandable alt_header="How can I query or preview metrics with the dbt Cloud CLI?">
 
 Check out the following video for a short video demo of how to query or preview metrics with the dbt Cloud CLI:

website/docs/docs/build/metrics-overview.md

@@ -21,8 +21,8 @@ The keys for metrics definitions are:
 | `description` | Describe your metric.   | Optional |
 | `type` | Define the type of metric, which can be `conversion`, `cumulative`, `derived`, `ratio`, or `simple`. | Required |
 | `type_params` | Additional parameters used to configure metrics. `type_params` are different for each metric type. | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`).  | Required |
 | `config` | Use the [`config`](/reference/resource-properties/config) property to specify configurations for your metric. Supports [`meta`](/reference/resource-configs/meta), [`group`](/reference/resource-configs/group), and [`enabled`](/reference/resource-configs/enabled) configurations.  | Optional |
-| `label` | The display name for your metric. This value will be shown in downstream tools.   | Required |
 | `filter` | You can optionally add a filter string to any metric type, applying filters to dimensions, entities, or time dimensions during metric computation. Consider it as your WHERE clause.   | Optional |
 
 Here's a complete example of the metrics spec configuration:
@@ -56,7 +56,7 @@ metrics:
 | `type_params` | Additional parameters used to configure metrics. `type_params` are different for each metric type. | Required |
 | `config` | Provide the specific configurations for your metric.   | Optional |
 | `meta` | Use the [`meta` config](/reference/resource-configs/meta) to set metadata for a resource.  | Optional |
-| `label` | The display name for your metric. This value will be shown in downstream tools.   | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`).   | Required |
 | `filter` | You can optionally add a filter string to any metric type, applying filters to dimensions, entities, or time dimensions during metric computation. Consider it as your WHERE clause.   | Optional |
 
 Here's a complete example of the metrics spec configuration:
@@ -123,7 +123,7 @@ metrics:
     owners:
       - [email protected]
     type: cumulative
-    label: Weekly Active Users
+    label: Weekly active users
     type_params:
       measure:
         name: active_users
@@ -144,7 +144,7 @@ metrics:
   - name: order_gross_profit
     description: Gross profit from each order.
     type: derived
-    label: Order Gross Profit
+    label: Order gross profit
     type_params:
       expr: revenue - cost
       metrics:
@@ -206,9 +206,8 @@ metrics:
 
 - `name`— Use this parameter to define the reference name of the metric. The name must be unique amongst metrics and can include lowercase letters, numbers, and underscores. You can use this name to call the metric from the dbt Semantic Layer API.
 
-<!--create_metric not supported yet
-**Note:** If you've already defined the measure using the `create_metric: True` parameter, you don't need to create simple metrics.  However, if you would like to include a constraint on top of the measure, you will need to create a simple type metric. 
--->
+**Note:** If you've already defined the measure using the `create_metric: True` parameter, you don't need to create simple metrics.  However, if you would like to include a constraint on top of the measure, you will need to create a simple type metric.
+
 ```yaml
 metrics:
   - name: cancellations

website/docs/docs/build/packages.md

@@ -94,7 +94,7 @@ Some package maintainers may wish to push prerelease versions of packages to the
 
 By default, `dbt deps` will not include prerelease versions when resolving package dependencies. You can enable the installation of prereleases in one of two ways:
 - Explicitly specifying a prerelease version in your `version` criteria
-- Setting `install-prerelease` to `true`, and providing a compatible version range
+- Setting `install_prerelease` to `true`, and providing a compatible version range
 
 For example, both of the following configurations would successfully install `0.4.5-a2` for the [`dbt_artifacts` package](https://hub.getdbt.com/brooklyn-data/dbt_artifacts/latest/):
 
@@ -108,7 +108,7 @@ packages:
 packages:
   - package: brooklyn-data/dbt_artifacts
     version: [">=0.4.4", "<0.4.6"]
-    install-prerelease: true
+    install_prerelease: true
 ```
 
 ### Git packages

website/docs/docs/build/project-variables.md

@@ -110,7 +110,7 @@ The order of precedence for variable declaration is as follows (highest priority
 
 </VersionBlock>
 
-If dbt is unable to find a definition for a variable after checking these four places, then a compilation error will be raised.
+If dbt is unable to find a definition for a variable after checking all possible variable declaration places, then a compilation error will be raised.
 
 **Note:** Variable scope is based on the node ultimately using that variable. Imagine the case where a model defined in the root project is calling a macro defined in an installed package. That macro, in turn, uses the value of a variable. The variable will be resolved based on the _root project's_ scope, rather than the package's scope.
 

website/docs/docs/build/ratio-metrics.md

@@ -8,14 +8,14 @@ tags: [Metrics, Semantic Layer]
 
 Ratio allows you to create a ratio between two metrics. You simply specify a numerator and a denominator metric. Additionally, you can apply a dimensional filter to both the numerator and denominator using a constraint string when computing the metric. 
 
- The parameters, description, and type for ratio metrics are: 
+ The parameters, description, and type for ratio metrics are:
 
 | Parameter | Description | Type |
 | --------- | ----------- | ---- |
 | `name` | The name of the metric. | Required |
 | `description` | The description of the metric. | Optional |
 | `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required |
-| `label` | The value that will be displayed in downstream tools. | Required |
+| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
 | `type_params` | The type parameters of the metric. | Required |
 | `numerator` | The name of the metric used for the numerator, or structure of properties. | Required |
 | `denominator` |  The name of the metric used for the denominator, or structure of properties. | Required  |
@@ -29,7 +29,7 @@ metrics:
   - name: The metric name # Required
     description: the metric description # Optional
     type: ratio # Required
-    label: The value that will be displayed in downstream tools #Required
+    label: String that defines the display value in downstream tools. (such as orders_total or "orders_total") #Required
     type_params: # Required
       numerator: The name of the metric used for the numerator, or structure of properties # Required
         name: Name of metric used for the numerator # Required
@@ -49,7 +49,7 @@ For advanced data modeling, you can use `fill_nulls_with` and `join_to_timespine
 metrics:
   - name: food_order_pct
     description: "The food order count as a ratio of the total order count"
-    label: Food Order Ratio
+    label: Food order ratio
     type: ratio
     type_params: 
       numerator: food_orders