add metric offset

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

@@ -6,7 +6,7 @@ sidebar_label: Derived
 tags: [Metrics, Semantic Layer]
 ---
 
-In MetricFlow, derived metrics are metrics created by defining an expression using other metrics. They allow performing calculations on top of existing metrics. This proves useful for combining metrics and applying arithmetic functions to aggregated columns, such as, you can define a profit metric. 
+In MetricFlow, derived metrics are metrics created by defining an expression using other metrics. They enable you to perform calculations with existing metrics. This is helpful for combining metrics and doing math functions on aggregated columns, like creating a profit metric. 
 
  The parameters, description, and type for derived metrics are: 
 
@@ -21,7 +21,8 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi
 | `metrics` |  The list of metrics used in the derived metrics. | Required  |
 | `alias` | Optional alias for the metric that you can use in the expr. | Optional |
 | `filter` | Optional filter to apply to the metric. | Optional |
-| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Required |
+| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. This can't be used with `offset_to_grain`. | Required |
+| `offset_to_grain` | Specifies the granularity or level of detail for the offset, such as a day. This means if you set your `offset_to_grain: day`, the offset is applied at the daily level. If you set it to "hour," it means the offset is at the hourly level. This can't be used with `offset_window`. | Required |
 
 The following displays the complete specification for derived metrics, along with an example.
 
@@ -37,7 +38,7 @@ metrics:
         - name: the name of the metrics. must reference a metric you have already defined # Required
           alias: optional alias for the metric that you can use in the expr # Optional
           filter: optional filter to apply to the metric # Optional
-          offset_window: set the period for the offset window i.e 1 month. This will return the value of the metric one month from the metric time. # Required
+          offset_window: set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. # Required
 ```
 
 ## Derived metrics example
@@ -85,17 +86,97 @@ metrics:
 
 ## Derived metric offset
 
-You may want to use an offset value of a metric in the definition of a derived metric. For example, you can model the retention rate by using a derived metric with an offset, which involves calculating (active customers at the end of the month/active customers at the beginning of the month).
+To perform calculations using a metric's value from a previous time period, you can add an offset parameter to a derived metric. For example, if you want to calculate period-over-period growth or track user retention, you can use this metric offset.
+
+**Note:** You must include the [`metric_time` dimension](/docs/build/dimensions#time) when querying a derived metric with an offset window.
+
+The following example displays how you can calculate monthly revenue growth using a 1-month offset window:
 
 ```yaml
-metrics:
-- name: user_retention
-  type: derived
-  type_params:
-    expr: active_customers/active_customers_t1m
-    metrics:
-      - name: active_customers # these are all metrics (can be a derived metric, meaning building a derived metric with derived metrics)
-      - name: active_customers
-        offset_window: 1 month
-        alias: active_customers_t1m
+- name: customer_retention
+    description: "Percentage of customers that are active now and those active 1 month ago"
+    label: customer_retention
+    type_params:
+      expr: (active_customers/ active_customers_prev_month)
+      metrics:
+        - name: active_customers
+          alias: current_active_customers
+        - name: active_customers
+          offset_window: 1 month
+          alias: active_customers_prev_month
+```
+
+### Offset windows and granularity
+
+You can query any granularity and offset window combination. The following examples queries a metric with a 7-day offset and a monthly grain:
+
+```yaml
+- name: d7_booking_change
+    description: "Difference between bookings now and 7 days ago"
+    type: derived
+    label: d7 Bookings Change
+    type_params:
+      expr: bookings - bookings_7_days_ago
+      metrics:
+        - name: bookings
+          alias: current_bookings
+        - name: bookings
+          offset_window: 7 days
+          alias: bookings_7_days_ago
+
+```
+
+**Using `offset_to_grain`**
+
+You can set an `offset_to_grain` to specify the granularity or level of detail for the offset, such as a day or hour. Something to note is that you can't use this with `offset_window`. The following example queries a metric with an hourly offset and a monthly grain:
+
+```yaml
+- name: d7_booking_change
+    description: "Calculate bookings per hour for the current month"
+    type: derived
+    label: d7 Bookings Change
+    type_params:
+      expr: bookings * bookings_hourly
+      metrics:
+        - name: bookings
+          alias: current_bookings
+        - name: bookings
+          offset_to_grain: hour
+          alias: bookings_hourly
+```
+
+### Derived metric offset calculation
+
+When you run the query  `mf query --metrics d7_booking_change --group-by metric_time__month` for the metric, here's how it's calculated:
+
+1. We retrieve the raw, unaggregated dataset with the specified measures and dimensions at the smallest level of detail, which is currently 'day'.
+2. Then, we perform an offset join on the daily dataset, followed by performing a date trunc and aggregation to the requested granularity.
+   For example, to calculate `d7_booking_change` for July 2017: 
+   - First we sum up all the booking values for each day in July to calculate the bookings metric.
+   - The following table displays the range of days that make up this monthly aggregation.
+
+|   | Orders | Metric_time |
+| - | ---- | -------- |
+|   | 330 | 2017-07-31 |
+|   | 7030 | 2017-07-30 to 2017-07-02 |
+|   | 78 | 2017-07-01 |
+| Total  | 7438 | 2017-07-01 |
+
+3. Next, we calculate July's bookings with a 7-day offset. The following table displays the range of days that make up this monthly aggregation. Note that the month begins 7 days later (offset by 7 days) on 2017-07-24.
+
+|   | Orders | Metric_time |
+| - | ---- | -------- |
+|   | 329 | 2017-07-24 |
+|   | 6840 | 2017-07-23  to 2017-06-35 |
+|   | 83 | 2017-06-24 |
+| Total  | 7252 | 2017-07-01 |
+
+4. Lastly, we calculate the derived metric and return the final result set:
+
+```bash
+bookings - bookings_7_days_ago would be compile as 7438 - 7252 = 186. 
 ```
+
+| d7_booking_change | metric_time__month |
+| ----------------- | ------------------ |
+| 186 | 2017-07-01 |