From a35e6135b1567eaa4c15e9e7989581cb68b0c7e8 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 19 Sep 2024 11:56:29 +0100 Subject: [PATCH 1/8] Update metricflow-time-spine.md adding clarifiation based on [thread in slack](https://dbt-labs.slack.com/archives/C03KHQRQUBX/p1726597063492349) --- website/docs/docs/build/metricflow-time-spine.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 18acf451a12..869e6dbb137 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -6,11 +6,13 @@ sidebar_label: "MetricFlow time spine" tags: [Metrics, Semantic Layer] --- -It's common in analytics engineering to have a date dimension or "time spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarter, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. +It's common in analytics engineering to have a date dimension or "time spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarters, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. -MetricFlow requires you to define a time spine table as a project level configuration, which then is used for various time-based joins and aggregations, like cumulative metrics. At a minimum, you need to define a time spine table for a daily grain. You can optionally define a time spine table for a different granularity, like hourly. +MetricFlow requires you to define a time spine table as a project-level configuration for time-based joins and aggregations, like cumulative metrics. You only need to configure time spine models that the Semantic Layer should recognize. At a minimum, define a time spine table for a daily grain. You can optionally define a time spine table for a different granularity, like hourly. Note that if you don’t have a date or calendar model in your project, you'll need to create one. -If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. +If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. + +For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years, refer to the [Dimensions page](/docs/build/dimensions#time?dimension=time_granularity) to find the full list of supported granularities. :::tip Previously, you were required to create a model called `metricflow_time_spine` in your dbt project. This is no longer required. However, you can build your time spine model from this table if you don't have another date dimension table you want to use in your project. @@ -38,6 +40,8 @@ models: ``` +For an example project, refer to our [Jaffle shop](https://github.com/dbt-labs/jaffle-sl-template/blob/main/models/marts/_models.yml) example. + Now, break down the configuration above. It's pointing to a model called `time_spine_daily`. It sets the time spine configurations under the `time_spine` key. The `standard_granularity_column` is the lowest grain of the table, in this case, it's hourly. It needs to reference a column defined under the columns key, in this case, `date_hour`. Use the `standard_granularity_column` as the join key for the time spine table when joining tables in MetricFlow. Here, the granularity of the `standard_granularity_column` is set at the column level, in this case, `hour`. From 63b1a139d8e87f68c36b3e6fceb4c028fcf31de7 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 19 Sep 2024 12:01:36 +0100 Subject: [PATCH 2/8] Update website/docs/docs/build/metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 869e6dbb137..080f5758ba6 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -12,7 +12,7 @@ MetricFlow requires you to define a time spine table as a project-level configur If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. -For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years, refer to the [Dimensions page](/docs/build/dimensions#time?dimension=time_granularity) to find the full list of supported granularities. +For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years, refer to the [Dimensions page](/docs/build/dimensions?dimension=time_gran#time) (time_granularity tab) to find the full list of supported granularities. :::tip Previously, you were required to create a model called `metricflow_time_spine` in your dbt project. This is no longer required. However, you can build your time spine model from this table if you don't have another date dimension table you want to use in your project. From 4bca24446be385ef1221d954685b0fad65939300 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 19 Sep 2024 12:10:25 +0100 Subject: [PATCH 3/8] Update metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 080f5758ba6..7835fda8138 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -8,7 +8,11 @@ tags: [Metrics, Semantic Layer] It's common in analytics engineering to have a date dimension or "time spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarters, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. -MetricFlow requires you to define a time spine table as a project-level configuration for time-based joins and aggregations, like cumulative metrics. You only need to configure time spine models that the Semantic Layer should recognize. At a minimum, define a time spine table for a daily grain. You can optionally define a time spine table for a different granularity, like hourly. Note that if you don’t have a date or calendar model in your project, you'll need to create one. +MetricFlow requires you to define a time spine table as a project-level configuration for time-based joins and aggregations, like cumulative metrics. +- You only need to configure time spine models that the Semantic Layer should recognize. +- At a minimum, define a time spine table for a daily grain. +- You can optionally define a time spine table for a different granularity, like hourly. +- Note that if you don’t have a date or calendar model in your project, you'll need to create one. If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. From 15d3c1447534a1b6452bca9ef133cf5c9e8228bf Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 20 Sep 2024 10:55:43 +0100 Subject: [PATCH 4/8] Update website/docs/docs/build/metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 7835fda8138..e9cc4b5ee6c 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -19,7 +19,9 @@ If you already have a date dimension or time spine table in your dbt project, yo For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years, refer to the [Dimensions page](/docs/build/dimensions?dimension=time_gran#time) (time_granularity tab) to find the full list of supported granularities. :::tip -Previously, you were required to create a model called `metricflow_time_spine` in your dbt project. This is no longer required. However, you can build your time spine model from this table if you don't have another date dimension table you want to use in your project. +Previously, you had to create a model called `metricflow_time_spine` in your dbt project. Now, if your project already includes a date dimension or time spine table, you can simply configure MetricFlow to use that table by updating the `model` setting in the Semantic Layer. + +If you don’t have a date dimension table, you can still create one by using the code snippet below to build your time spine model. ::: From b795f97785ddd46e2c8e4eb2875179df3cbeb54e Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 20 Sep 2024 11:06:44 +0100 Subject: [PATCH 5/8] Update website/docs/docs/build/metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index e9cc4b5ee6c..211c2a3b0e9 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -13,6 +13,7 @@ MetricFlow requires you to define a time spine table as a project-level configur - At a minimum, define a time spine table for a daily grain. - You can optionally define a time spine table for a different granularity, like hourly. - Note that if you don’t have a date or calendar model in your project, you'll need to create one. +- If you're looking to specify the grain of a time dimension so that MetricFlow can transform the underlying column to the required granularity, refer to the [Time granularity documentation](/docs/build/dimensions?dimension=time_gran) If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. From 89dab9def33bb5a49a22c0c00fd9c8a10e970960 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 20 Sep 2024 11:10:06 +0100 Subject: [PATCH 6/8] Update website/docs/docs/build/metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 211c2a3b0e9..c12ecb06004 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -17,7 +17,7 @@ MetricFlow requires you to define a time spine table as a project-level configur If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. -For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years, refer to the [Dimensions page](/docs/build/dimensions?dimension=time_gran#time) (time_granularity tab) to find the full list of supported granularities. +For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years. Refer to the [Dimensions page](/docs/build/dimensions?dimension=time_gran#time) (time_granularity tab) to find the full list of supported granularities. :::tip Previously, you had to create a model called `metricflow_time_spine` in your dbt project. Now, if your project already includes a date dimension or time spine table, you can simply configure MetricFlow to use that table by updating the `model` setting in the Semantic Layer. From be097abafb4304a7d12fd4c7ce54896dc46b0633 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 20 Sep 2024 17:17:55 +0100 Subject: [PATCH 7/8] Update website/docs/docs/build/metricflow-time-spine.md --- website/docs/docs/build/metricflow-time-spine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index c12ecb06004..1acc353102d 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -8,7 +8,7 @@ tags: [Metrics, Semantic Layer] It's common in analytics engineering to have a date dimension or "time spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarters, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. -MetricFlow requires you to define a time spine table as a project-level configuration for time-based joins and aggregations, like cumulative metrics. +MetricFlow requires you to define a time spine table as a model-level configuration in the Semantic Layer for time-based joins and aggregations, such as cumulative metrics. This configuration informs dbt which model should be used for time range joins. It is especially useful for cumulative metrics or calculating time-based offsets. - You only need to configure time spine models that the Semantic Layer should recognize. - At a minimum, define a time spine table for a daily grain. - You can optionally define a time spine table for a different granularity, like hourly. From f7bfdbe5a05998280af98775d9f70ce51e61beb2 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 20 Sep 2024 17:23:50 +0100 Subject: [PATCH 8/8] Update metricflow-time-spine.md --- .../docs/docs/build/metricflow-time-spine.md | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/website/docs/docs/build/metricflow-time-spine.md b/website/docs/docs/build/metricflow-time-spine.md index 1acc353102d..7fd196f7f7c 100644 --- a/website/docs/docs/build/metricflow-time-spine.md +++ b/website/docs/docs/build/metricflow-time-spine.md @@ -6,16 +6,24 @@ sidebar_label: "MetricFlow time spine" tags: [Metrics, Semantic Layer] --- -It's common in analytics engineering to have a date dimension or "time spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarters, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. - -MetricFlow requires you to define a time spine table as a model-level configuration in the Semantic Layer for time-based joins and aggregations, such as cumulative metrics. This configuration informs dbt which model should be used for time range joins. It is especially useful for cumulative metrics or calculating time-based offsets. -- You only need to configure time spine models that the Semantic Layer should recognize. -- At a minimum, define a time spine table for a daily grain. -- You can optionally define a time spine table for a different granularity, like hourly. +It's common in analytics engineering to have a date dimension or "time-spine" table as a base table for different types of time-based joins and aggregations. The structure of this table is typically a base column of daily or hourly dates, with additional columns for other time grains, like fiscal quarters, defined based on the base column. You can join other tables to the time spine on the base column to calculate metrics like revenue at a point in time, or to aggregate to a specific time grain. + +MetricFlow requires you to define a time-spine table as a model-level configuration in the Semantic Layer for time-based joins and aggregations, such as cumulative metrics. This configuration informs dbt which model should be used for time range joins. It is especially useful for cumulative metrics or calculating time-based offsets. The time-spine model is joined to other tables when calculating certain types of metrics or dimensions. MetricFlow will join the time-spine model in the compiled SQL for the following types of metrics and dimensions: +- [Cumulative metrics](/docs/build/cumulative) +- [Metric offsets](/docs/build/derived#derived-metric-offset) +- [Conversion metrics](/docs/build/conversion) +- [Slowly Changing Dimensions](/docs/build/dimensions#scd-type-ii) +- [Metrics](/docs/build/metrics-overview) with the `join_to_timespine` configuration set to true +To see the generated SQL for the metric and dimension types that use time-spine joins, refer to the respective documentation or add the `compile=True` flag when querying the Semantic Layer to return the compiled SQL. + +#### Configuring time-spine +- You only need to configure time-spine models that the Semantic Layer should recognize. +- At a minimum, define a time-spine table for a daily grain. +- You can optionally define a time-spine table for a different granularity, like hourly. - Note that if you don’t have a date or calendar model in your project, you'll need to create one. - If you're looking to specify the grain of a time dimension so that MetricFlow can transform the underlying column to the required granularity, refer to the [Time granularity documentation](/docs/build/dimensions?dimension=time_gran) -If you already have a date dimension or time spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. +If you already have a date dimension or time-spine table in your dbt project, you can point MetricFlow to this table by updating the `model` configuration to use this table in the Semantic Layer. This is a model-level configuration that tells dbt to use the model for time range joins in the Semantic Layer. For example, given the following directory structure, you can create two time spine configurations, `time_spine_hourly` and `time_spine_daily`. MetricFlow supports granularities ranging from milliseconds to years. Refer to the [Dimensions page](/docs/build/dimensions?dimension=time_gran#time) (time_granularity tab) to find the full list of supported granularities.