Add time interval reference examples to dimensions and metrics documentation

references/dimensions.mdx

@@ -414,6 +414,42 @@ You can set custom versions of time intervals by using additional dimensions and
               groups: ["Delivery Date"]
 ```
 
+### Reference time intervals in other dimensions
+
+You can reference specific time intervals of a dimension in other dimensions. When you define time intervals for a dimension (like `session_start`), Lightdash creates separate dimensions for each interval (e.g., `session_start_day`, `session_start_month`). You can reference these in custom SQL for other dimensions.
+
+For example, if you have a `user_created_at` dimension with time intervals defined, you can calculate the duration between two dates using the `DAY` interval:
+
+```yaml
+  - name: user_created_at
+    meta:
+      dimension:
+        type: timestamp
+        time_intervals:
+        - DAY_OF_WEEK_NAME
+        - WEEK
+        - MONTH
+        - RAW
+        - DAY
+        - HOUR_OF_DAY_NUM
+        - QUARTER
+  - name: first_purchase_at
+    meta:
+      dimension:
+        type: timestamp
+        time_intervals:
+        - DAY
+        - MONTH
+        - QUARTER
+  - name: duration
+    meta:
+      dimension:
+        type: number
+        sql: EXTRACT(DAY FROM ${first_purchase_at_day} - ${user_created_at_day})
+```
+
+In this example, `${user_created_at_day}` and `${first_purchase_at_day}` reference the `DAY` time interval versions of the `user_created_at` and `first_purchase_at` dimensions.
+
 ## Groups
 
 You can group your dimensions and metrics in the sidebar using the `groups` parameter.
@@ -751,3 +787,34 @@ models:
               type: max
               sql: ${version}
 ```
+
+### Referencing time intervals in additional dimensions
+
+You can reference time interval dimensions within additional dimensions. This is useful for creating custom logic based on specific time intervals.
+
+For example, you can create a tier based on whether a specific time interval has a value:
+
+```yaml
+  - name: session_start
+    meta:
+      dimension:
+        type: timestamp
+        time_intervals:
+        - DAY_OF_WEEK_NAME
+        - WEEK
+        - MONTH
+        - RAW
+        - DAY
+        - HOUR_OF_DAY_NUM
+        - QUARTER
+      additional_dimensions:
+        extra_session_start_tier:
+          type: string
+          sql: |
+            CASE 
+              WHEN ${session_start_month} IS NOT NULL THEN 'month' 
+              ELSE 'else'
+            END
+```
+
+In this example, the additional dimension `extra_session_start_tier` references `${session_start_month}`, which is the `MONTH` time interval of the `session_start` dimension.

references/metrics.mdx

@@ -536,6 +536,18 @@ metrics:
     sql: 'IF(${subscriptions.is_active}, ${user_id}, NULL)'
 ```
 
+### Referencing time intervals in custom SQL
+
+You can reference specific time intervals of dimensions in custom SQL for aggregate metrics. When a dimension has time intervals defined, you can reference the specific interval by appending the interval name to the dimension name.
+
+```yaml
+      max_month:
+        type: max
+        sql: ${session_start_month}
+```
+
+In this example, the metric references `${session_start_month}`, which is the `MONTH` time interval of the `session_start` dimension. This allows you to perform aggregations on specific time interval versions of your dimensions.
+
 ## Using custom SQL in non-aggregate metrics
 
 In non-aggregate metrics, you can reference any other metric from the given model and any joined models. You **can’t reference other dimensions.**
@@ -590,6 +602,20 @@ The list of fields must be made of dimension names (no metrics) from the base ta
 
 The order that the fields are listed in `show_underlying_values` is the order that they'll appear in on the `view underlying data` table.
 
+### Referencing time intervals in show underlying values
+
+You can reference specific time intervals of dimensions in the `show_underlying_values` list. When a dimension has time intervals defined, you can reference the specific interval by appending the interval name to the dimension name (e.g., `session_start_month`, `session_end_quarter`).
+
+```yaml
+      count:
+        type: count
+        show_underlying_values:
+          - session_start_month
+          - session_end_quarter
+```
+
+In this example, `session_start_month` and `session_end_quarter` reference the `MONTH` and `QUARTER` time intervals of the `session_start` and `session_end` dimensions respectively.
+
 ## Groups
 
 You can group your dimensions and metrics in the sidebar using the `groups` parameter.
@@ -751,6 +777,19 @@ models:
                 - web_sessions.is_bot_user: false
 ```
 
+### Referencing time intervals in filters
+
+You can reference specific time intervals of dimensions in metric filters. When a dimension has time intervals defined, you can filter on the specific interval by appending the interval name to the dimension name (e.g., `session_start_day`).
+
+```yaml
+      count:
+        type: count
+        filters:
+          - session_start_day: "!null"
+```
+
+In this example, the filter checks that `session_start_day` (the `DAY` time interval of the `session_start` dimension) is not null.
+
 ### Metric filters cannot be used with non-aggregate metrics
 
 You can't use filters with non-aggregate metric types. Instead, if your non-aggregate metrics are referencing aggregate metric types, you need to apply metric filters to the aggregate metrics.