From b49a75b1a895f842a5b4c518b271c321af52193d Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Fri, 2 Aug 2024 15:47:27 +0100 Subject: [PATCH] add --- website/docs/docs/build/dimensions.md | 12 ++- .../docs/docs/build/metricflow-time-spine.md | 44 ++--------- website/docs/docs/build/metrics-overview.md | 75 +++---------------- website/docs/docs/build/semantic-models.md | 2 +- .../docs/docs/build/sub-daily-granularity.md | 62 +++++++++++++++ website/sidebars.js | 1 + 6 files changed, 87 insertions(+), 109 deletions(-) create mode 100644 website/docs/docs/build/sub-daily-granularity.md diff --git a/website/docs/docs/build/dimensions.md b/website/docs/docs/build/dimensions.md index d74bc773ea9..a0ecf14db97 100644 --- 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). @@ -173,7 +171,7 @@ measures: -`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 index 9695d73562d..98c03ab02b5 100644 --- 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. - + @@ -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. - - - -```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 -``` - +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? -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 index c74bc2a9f9e..bea99230faa 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -82,7 +82,7 @@ metrics: {{ Dimension('entity__name') }} > 0 and {{ Dimension(' entity__another_name') }} is not null and {{ Metric('metric_name', group_by=['entity_name']) }} > 5 ``` - + @@ -90,7 +90,13 @@ import SLCourses from '/snippets/_sl-course.md'; -### 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: ``` -### 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: ``` -### 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: ``` -### 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** — 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`. - - - -```yaml -metrics: - - name: my_metrics - ... - default_grain: day # Optional: defaults to day -``` - - -#### 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. - - - -```yaml -dimensions: - - name: ordered_at - type: time - type_params: - time_granularity: hour - -``` - - -### 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 index e136b2a064d..2678af7d57f 100644 --- 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 new file mode 100644 index 00000000000..84abbcc3285 --- /dev/null +++ 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`. + + + + ```yaml + metrics: + - name: my_metrics + ... + default_grain: day # Optional: defaults to day + ``` + + +- #### `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. + + + + ```yaml + dimensions: + - name: ordered_at + type: time + type_params: + time_granularity: hour + + ``` + + +### 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 index 377c353e9be..344aad11186 100644 --- 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",