add

dbt-labs · Aug 2, 2024 · b49a75b · b49a75b
1 parent 6626a1c
commit b49a75b
Show file tree

Hide file tree

Showing 6 changed files with 87 additions and 109 deletions.
diff --git a/website/docs/docs/build/dimensions.md b/website/docs/docs/build/dimensions.md
@@ -105,14 +105,13 @@ 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.
+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 sub-daily like hour, or week, month, quarter, year, and so on. MetricFlow supports these granularities, which can be specified using the `time_granularity` parameter.
 :::
 
 Time has additional parameters specified under the `type_params` section. When you query one or more metrics in MetricFlow using the CLI, the default time dimension for a single metric is the aggregation time dimension, which you can refer to as `metric_time` or use the dimensions' name. 
 
 You can use multiple time groups in separate metrics. For example, the `users_created` metric uses `created_at`, and the `users_deleted` metric uses `deleted_at`:
 
-
 ```bash
 # dbt Cloud users
 dbt sl query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year
@@ -121,8 +120,7 @@ dbt sl query --metrics users_created,users_deleted --group-by metric_time__year
 mf query --metrics users_created,users_deleted --group-by metric_time__year --order-by metric_time__year
 ```
 
-
-You can set `is_partition` for time or categorical dimensions to define specific time spans. Additionally, use the `type_params` section to set `time_granularity` to adjust aggregation detail (like daily, weekly, and so on):
+You can set `is_partition` for time or categorical dimensions to define specific time spans. Additionally, use the `type_params` section to set `time_granularity` to adjust aggregation detail (like sub-daily (hourly), daily, weekly, and so on). For more sub-daily configuration details, refer to [sub-daily granularity](/docs/build/sub-daily).
 
 <Tabs>
 
@@ -173,7 +171,7 @@ measures:
 
 <TabItem value="time_gran" label="time_granularity">
 
-`time_granularity` specifies the smallest level of detail that a measure or metric should be reported at, such as daily, weekly, monthly, quarterly, or yearly. Different granularity options are available, and each metric must have a specified granularity. For example, a metric specified with weekly granularity couldn't be aggregated to a daily grain. 
+`time_granularity` specifies the smallest level of detail that a measure or metric should be reported at, such as [sub-daily](/docs/build/metrics-overview#sub-daily-granularity), daily, weekly, monthly, quarterly, or yearly. Different granularity options are available, and each metric must have a specified granularity. For example, a metric specified with weekly granularity couldn't be aggregated to a daily grain. 
 
 The current options for time granularity are day, week, month, quarter, and year. 
 
@@ -187,14 +185,14 @@ dimensions:
     expr: date_trunc('day', ts_created) # ts_created is the underlying column name from the table 
     is_partition: True 
     type_params:
-      time_granularity: day
+      time_granularity: hour # or second, or millisecond etc
   - 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:
-      time_granularity: day
+      time_granularity: hour # or second, or millisecond etc
 
 measures:
   - name: users_deleted

diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md
@@ -6,11 +6,11 @@ sidebar_label: "MetricFlow time spine"
 tags: [Metrics, Semantic Layer]
 ---
 
-MetricFlow uses a timespine table to construct cumulative metrics. By default, MetricFlow expects the timespine table to be named `metricflow_time_spine` and doesn't support using a different name.
+MetricFlow uses a timespine table to construct cumulative metrics. By default, MetricFlow expects the timespine table to be named `metricflow_time_spine` and doesn't support using a different name. 
 
-To create this table, you need to create a model in your dbt project called `metricflow_time_spine` and add the following code:
+To create this table, you need to create a model in your dbt project called `metricflow_time_spine` and add the following code. This example uses a `day` granularity to generate a table with one row per day. This is useful for metrics that need a daily aggregation.
 
-<File name='metricflow_time_spine.sql'>
+<File name='metricflow_time_spine_day.sql'>
 
 <VersionBlock lastVersion="1.6">
 
@@ -130,46 +130,14 @@ from final
 
 You only need to include the `date_day` column in the table. MetricFlow can handle broader levels of detail, but it doesn't currently support finer grains.
 
-## Daily time spine
-This example uses `dbt.date_spine` with a `day` granularity to generate a table with one row per day. This is useful for metrics that need a daily aggregation.
-
-<File name='metricflow_time_spine_day.sql'>
-
-```sql
--- filename: metricflow_time_spine_day.sql
-{{
-    config(
-        materialized = 'table',
-    )
-}}
-
-with days as (
-
-    {{
-        dbt.date_spine(
-            'day',
-            "to_date('01/01/2000','mm/dd/yyyy')",
-            "to_date('01/01/2030','mm/dd/yyyy')"
-        )
-    }}
-
-),
-
-final as (
-    select cast(date_day as date) as date_day
-    from days
-)
+## Hourly time spine
 
-select * from final
-```
-</File>
+This example uses `dbt.date_spine` with an `hour` granularity to generate a table with one row per hour. This is needed for hourly data aggregation and other sub-daily analyses. 
 
-## Hourly time spine
+WHAT ARE OTHER OPTIONS?? TO ADD BOTH, DO USERS NEED TWO FILES (HOUR AND DAY) OR CAN THEY BE COMBINED?
 
 <File name='metricflow_time_spine_hour.sql'>
 
-This example uses `dbt.date_spine` with an `hour` granularity to generate a table with one row per hour. This is needed for hourly data aggregation and other sub-daily analyses.
-
 ```sql
 -- filename: metricflow_time_spine_hour.sql
 {{

diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md
@@ -82,15 +82,21 @@ metrics:
       {{  Dimension('entity__name') }} > 0 and {{ Dimension(' entity__another_name') }} is not
       null and {{ Metric('metric_name', group_by=['entity_name']) }} > 5
 ```
-<File>
+</File>
 
 </VersionBlock>
 
 import SLCourses from '/snippets/_sl-course.md';
 
 <SLCourses/>
 
-### Conversion metrics
+## Sub-daily granularity
+
+Sub-daily granularity enables you to query metrics at granularities at finer time grains below a day, such as hourly, minute, or even by the second. It support anything that `date_trunc` supports. This can be useful if you want more detailed analysis and for datasets where you need more granular time data, such as minute-by-minute event tracking.
+
+For more configuration details, refer to [sub-daily granularity](/docs/build/sub-daily).
+
+## Conversion metrics
 
 [Conversion metrics](/docs/build/conversion) help you track when a base event and a subsequent conversion event occur for an entity within a set time period.
 
@@ -121,7 +127,7 @@ metrics:
 ```
 </File>
 
-### Cumulative metrics
+## Cumulative metrics
 
 [Cumulative metrics](/docs/build/cumulative) aggregate a measure over a given window. If no window is specified, the window will accumulate the measure over all of the recorded time period. Note that you will need to create the [time spine model](/docs/build/metricflow-time-spine) before you add cumulative metrics.
 
@@ -142,7 +148,7 @@ metrics:
 ```
 </File>
 
-### Derived metrics
+## Derived metrics
 
 [Derived metrics](/docs/build/derived) are defined as an expression of other metrics. Derived metrics allow you to do calculations on top of metrics. 
 
@@ -182,7 +188,7 @@ metrics:
 ```
 -->
 
-### Ratio metrics 
+## Ratio metrics 
 
 [Ratio metrics](/docs/build/ratio) involve a numerator metric and a denominator metric. A  `filter` string  can be applied to both the numerator and denominator or separately to the numerator or denominator.
 
@@ -210,7 +216,7 @@ metrics:
 ```
 </File>
 
-### Simple metrics
+## Simple metrics
 
 [Simple metrics](/docs/build/simple) point directly to a measure. You may think of it as a function that takes only one measure as the input.
 
@@ -265,63 +271,6 @@ You can set more metadata for your metrics, which can be used by other tools lat
 
 - **Description** &mdash;  Write a detailed description of the metric.
 
-## Sub-daily granularity
-
-Sub-daily granularity enables you to query metrics at granularities at finer time grains below a day, such as hourly, minute, or even by the second. It support anything that `date_trunc` supports. Use sub-daily granularity for cumulative metrics, time spine models at sub-daily grains, and default grain settings for metrics.
-
-This is particularly useful for more detailed analysis and for datasets where high-resolution time data is required, such as minute-by-minute event tracking. 
-
-### Usage
-There are two ways to specify sub-daily granularity: `default_grain` and `time_granularity`. This section explains how to use both methods, how they also interact, and which one takes precedence. 
-
-#### `default_grain`
-
-Use the `default_grain` parameter in the metric-level metric config to specify the default granularity for querying the metric when no specific granularity is defined. It allows specifying the most common or sensible default, like day, hour, and so on. 
-
-This parameter is optional and defaults to `day`.
-
-<File name="models/metrics/file_name.yml" >
-
-```yaml
-metrics:
-  - name: my_metrics
-    ...
-    default_grain: day # Optional: defaults to day
-```
-</File>
-
-#### time_granularity
-
-Use the `time_granularity` parameter at the dimension-level with the time dimension `type_params` to specify the level of granularity directly on the data, like hour, minute, second, and so on. It affects how the data is truncated or aggregated in queries.
-
-<File name="models/metrics/file_name.yml" >
-
-```yaml
-dimensions:
-  - name: ordered_at
-    type: time
-    type_params:
-      time_granularity: hour
-
-```
-</File>
-
-### Precedence
-When querying metrics by `metric_time`, MetricFlow currently defaults to the grain of the `agg_time_dimension`. If you want to query metrics at a different grain, you can use the `time_granularity` type parameter in time dimensions.
-
-The following table explains how `default_grain` and `time_granularity` interact and the resulting query granularity:
-
-| Context | `default_grain` | `time_granularity` | Result |
-| Only `default_grain` specified | `day` | `hour` | Query at `hour` granularity |
-| Only `time_granularity` specified | - | `hour` | Query at `hour` granularity |
-| Both specified, same value | `hour` | `hour` | Query at `hour` granularity |
-| Both specified, different value | `day` | `minute` | Query at `minute` granularity |
-| Both not specified | - | - | Defaults to `day` |
-
-
-Implementation using the `time_granularity` type parameter in time dimensions.
-Examples of using DATE_TRUNC with sub-daily granularities in SQL.
-
 ## Related docs
 
 - [Semantic models](/docs/build/semantic-models)

diff --git a/website/docs/docs/build/semantic-models.md b/website/docs/docs/build/semantic-models.md
@@ -84,7 +84,7 @@ semantic_models:
       - name: transaction_date
         type: time
         type_params:
-          time_granularity: day
+          time_granularity: day # Additional options include sub-daily like hour, week, month, quarter, year, and so on.
 
       - name: transaction_location
         type: categorical

diff --git a/website/docs/docs/build/sub-daily-granularity.md b/website/docs/docs/build/sub-daily-granularity.md
@@ -0,0 +1,62 @@
+---
+title: Sub-daily granularity
+id: "sub-daily"
+description: "Sub-daily granularity enables you to query metrics at granularities at finer time grains below a day, such as hourly, minute, or even by the second. "
+sidebar_label: "Sub-daily granularity"
+tags: [Metrics, Semantic Layer]
+pagination_next: "docs/build/conversion"
+---
+
+
+Sub-daily granularity enables you to query metrics at granularities at finer time grains below a day, such as hourly, minute, or even by the second. It support anything that `date_trunc` supports. Use sub-daily granularity for cumulative metrics, time spine models at sub-daily grains, and default grain settings for metrics.
+
+This is particularly useful for more detailed analysis and for datasets where high-resolution time data is required, such as minute-by-minute event tracking. 
+
+### Usage
+There are two ways to specify sub-daily granularity: `default_grain` and `time_granularity`. This section explains how to use both methods, how they also interact, and which one takes precedence. 
+
+- #### `default_grain`
+  Use the `default_grain` parameter in the metric-level metric config to specify the default granularity for querying the metric when no specific granularity is defined. It allows specifying the most common or sensible default, like day, hour, and so on.
+
+  This parameter is optional and defaults to `day`.
+
+    <File name="models/metrics/file_name.yml" >
+
+    ```yaml
+    metrics:
+    - name: my_metrics
+        ...
+        default_grain: day # Optional: defaults to day
+    ```
+    </File>
+
+- #### `time_granularity`
+  Use the `time_granularity` parameter at the dimension-level with the [time dimension](/docs/build/dimensions#time) `type_params` to specify the level of granularity directly on the data, like hour, minute, second, and so on. It affects how the data is truncated or aggregated in queries.
+
+    <File name="models/metrics/file_name.yml" >
+
+    ```yaml
+    dimensions:
+    - name: ordered_at
+        type: time
+        type_params:
+          time_granularity: hour
+
+    ```
+    </File>
+
+### Precedence
+When querying metrics by `metric_time`, MetricFlow currently defaults to the grain of the `agg_time_dimension`. If you want to query metrics at a different grain, you can use the `time_granularity` type parameter in time dimensions.
+
+The following table explains how `default_grain` and `time_granularity` interact and the resulting query granularity:
+
+| Context | `default_grain` | `time_granularity` | Result |
+| --- | --- | --- | --- |
+| Only `default_grain` specified | `day` | `hour` | Query at `hour` granularity |
+| Only `time_granularity` specified | - | `hour` | Query at `hour` granularity |
+| Both specified, same value | `hour` | `hour` | Query at `hour` granularity |
+| Both specified, different value | `day` | `minute` | Query at `minute` granularity |
+| Both not specified | - | - | Defaults to `day` |
+
+Implementation using the `time_granularity` type parameter in time dimensions.
+Examples of using DATE_TRUNC with sub-daily granularities in SQL.
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -380,6 +380,7 @@ const sidebarSettings = {
               link: { type: "doc", id: "docs/build/metrics-overview" },
               items: [
                 "docs/build/metrics-overview",
+                "docs/build/sub-daily",
                 "docs/build/conversion",
                 "docs/build/cumulative",
                 "docs/build/derived",