From c0fd4c783ed5a397fdcb8dfd9a1b68bedfe0ed3c Mon Sep 17 00:00:00 2001 From: Jordan Stein Date: Thu, 12 Oct 2023 19:13:03 -0700 Subject: [PATCH 1/5] add docs for cumulative metrics limitations --- website/docs/docs/build/cumulative-metrics.md | 7 +++++++ website/docs/docs/build/dimensions.md | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 3104fd7578a..b4b491b1cf8 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -36,6 +36,13 @@ metrics: ``` +## Cumulative metrics limiations +Cumulative metrics are currently under active development and have the following limitations: + +1. Cumulative metrics can only be queried using [metric_time](../website/docs/docs/build/dimensions.md) dimension. If you don't use metric_time in the query the cumulative metric will return incorrect results because it won't do the time spine join. This means you cannot refrence time dimensions other then the metric_time in the query. +2. If you do use metric_time in the query filter, but you do NOT use start_time and end_time, cumulative metrics will left-censor the input data. For example, if you query a cumulative metric with a 7 day window with the filter {{ TimeDimension('metric_time') }} BETWEEN '2023-08-15' AND '2023-08-30' the values for 2023-08-15 through 2023-08-20 will return results with missing data, because we apply the metric_time filter to the aggregation input. To avoid this, you must use start_time and end_time in the query filter. + + ## Cumulative metrics example diff --git a/website/docs/docs/build/dimensions.md b/website/docs/docs/build/dimensions.md index 49ae9045021..c82a9f8ced4 100644 --- a/website/docs/docs/build/dimensions.md +++ b/website/docs/docs/build/dimensions.md @@ -102,7 +102,7 @@ dimensions: 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. ::: -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 primary time dimension, which you can refer to as `metric_time` or use the dimensions' name. +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`: From ecbed3da9c685118e5dd5bc5d36b1f8257b323a2 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Oct 2023 10:30:51 +0100 Subject: [PATCH 2/5] Update website/docs/docs/build/cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index b4b491b1cf8..22f2034ee9a 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -36,7 +36,7 @@ metrics: ``` -## Cumulative metrics limiations +## Limitations Cumulative metrics are currently under active development and have the following limitations: 1. Cumulative metrics can only be queried using [metric_time](../website/docs/docs/build/dimensions.md) dimension. If you don't use metric_time in the query the cumulative metric will return incorrect results because it won't do the time spine join. This means you cannot refrence time dimensions other then the metric_time in the query. From cd2117f9bba61589e301e7dbee7ccfa428fab33b Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Oct 2023 10:41:21 +0100 Subject: [PATCH 3/5] Update website/docs/docs/build/cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 22f2034ee9a..375de351682 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -39,7 +39,7 @@ metrics: ## Limitations Cumulative metrics are currently under active development and have the following limitations: -1. Cumulative metrics can only be queried using [metric_time](../website/docs/docs/build/dimensions.md) dimension. If you don't use metric_time in the query the cumulative metric will return incorrect results because it won't do the time spine join. This means you cannot refrence time dimensions other then the metric_time in the query. +1. You can only use the [`metric_time` dimension](/docs/docs/build/dimensions#time) to check cumulative metrics. If you don't use `metric_time` in the query, the cumulative metric will return incorrect results because it won't perform the time spine join. This means you cannot reference time dimensions other than the `metric_time` in the query. 2. If you do use metric_time in the query filter, but you do NOT use start_time and end_time, cumulative metrics will left-censor the input data. For example, if you query a cumulative metric with a 7 day window with the filter {{ TimeDimension('metric_time') }} BETWEEN '2023-08-15' AND '2023-08-30' the values for 2023-08-15 through 2023-08-20 will return results with missing data, because we apply the metric_time filter to the aggregation input. To avoid this, you must use start_time and end_time in the query filter. From b0d62aa1f9d5743e5d19768f314c45ab40b4e85e Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Oct 2023 10:46:00 +0100 Subject: [PATCH 4/5] Update website/docs/docs/build/cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 375de351682..d9736ec3695 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -40,7 +40,7 @@ metrics: Cumulative metrics are currently under active development and have the following limitations: 1. You can only use the [`metric_time` dimension](/docs/docs/build/dimensions#time) to check cumulative metrics. If you don't use `metric_time` in the query, the cumulative metric will return incorrect results because it won't perform the time spine join. This means you cannot reference time dimensions other than the `metric_time` in the query. -2. If you do use metric_time in the query filter, but you do NOT use start_time and end_time, cumulative metrics will left-censor the input data. For example, if you query a cumulative metric with a 7 day window with the filter {{ TimeDimension('metric_time') }} BETWEEN '2023-08-15' AND '2023-08-30' the values for 2023-08-15 through 2023-08-20 will return results with missing data, because we apply the metric_time filter to the aggregation input. To avoid this, you must use start_time and end_time in the query filter. +2. If you use `metric_time` in your query filter but don't include "start_time" and "end_time," cumulative metrics will left-censor the input data. For example, if you query a cumulative metric with a 7-day window with the filter `{{ TimeDimension('metric_time') }} BETWEEN '2023-08-15' AND '2023-08-30' `, the values for `2023-08-15` to `2023-08-20` return missing or incomplete data. This is because we apply the `metric_time` filter to the aggregation input. To avoid this, you must use `start_time` and `end_time` in the query filter. ## Cumulative metrics example From 9330136658e606c5a3f36f64c43bd1f7f9c1b6ab Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Oct 2023 10:55:55 +0100 Subject: [PATCH 5/5] Update website/docs/docs/build/cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index d9736ec3695..708045c1f3e 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -39,7 +39,7 @@ metrics: ## Limitations Cumulative metrics are currently under active development and have the following limitations: -1. You can only use the [`metric_time` dimension](/docs/docs/build/dimensions#time) to check cumulative metrics. If you don't use `metric_time` in the query, the cumulative metric will return incorrect results because it won't perform the time spine join. This means you cannot reference time dimensions other than the `metric_time` in the query. +1. You can only use the [`metric_time` dimension](/docs/build/dimensions#time) to check cumulative metrics. If you don't use `metric_time` in the query, the cumulative metric will return incorrect results because it won't perform the time spine join. This means you cannot reference time dimensions other than the `metric_time` in the query. 2. If you use `metric_time` in your query filter but don't include "start_time" and "end_time," cumulative metrics will left-censor the input data. For example, if you query a cumulative metric with a 7-day window with the filter `{{ TimeDimension('metric_time') }} BETWEEN '2023-08-15' AND '2023-08-30' `, the values for `2023-08-15` to `2023-08-20` return missing or incomplete data. This is because we apply the `metric_time` filter to the aggregation input. To avoid this, you must use `start_time` and `end_time` in the query filter.