From 2f28e2a676dbd54cd552c9d47390ef488f940195 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Tue, 13 Feb 2024 16:18:03 +0000 Subject: [PATCH 01/19] snippet and linear tasks --- website/docs/docs/build/build-metrics-intro.md | 7 +------ website/docs/docs/build/cumulative-metrics.md | 6 +++--- website/docs/docs/build/derived-metrics.md | 6 ------ website/docs/docs/build/metrics-overview.md | 5 ++++- website/docs/docs/build/ratio-metrics.md | 8 ++------ website/docs/docs/build/semantic-models.md | 5 +++++ website/docs/docs/build/simple.md | 7 ++++--- website/docs/docs/build/sl-getting-started.md | 4 ++++ .../docs/use-dbt-semantic-layer/avail-sl-integrations.md | 1 + website/docs/docs/use-dbt-semantic-layer/gsheets.md | 8 ++++++-- .../docs/docs/use-dbt-semantic-layer/quickstart-sl.md | 9 ++++++--- website/docs/docs/use-dbt-semantic-layer/setup-sl.md | 4 ++++ website/docs/docs/use-dbt-semantic-layer/tableau.md | 6 +++++- website/docs/guides/sl-migration.md | 1 + website/docs/guides/sl-partner-integration-guide.md | 4 ++++ website/snippets/_sl-course.md | 8 ++++++++ 16 files changed, 58 insertions(+), 31 deletions(-) create mode 100644 website/snippets/_sl-course.md diff --git a/website/docs/docs/build/build-metrics-intro.md b/website/docs/docs/build/build-metrics-intro.md index d6b97be699b..ad6ddb16a10 100644 --- a/website/docs/docs/build/build-metrics-intro.md +++ b/website/docs/docs/build/build-metrics-intro.md @@ -11,14 +11,12 @@ pagination_prev: null Use MetricFlow in dbt to centrally define your metrics. As a key component of the [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl), MetricFlow is responsible for SQL query construction and defining specifications for dbt semantic models and metrics. It uses familiar constructs like semantic models and metrics to avoid duplicative coding, optimize your development workflow, ensure data governance for company metrics, and guarantee consistency for data consumers. - MetricFlow allows you to: - Intuitively define metrics in your dbt project - Develop from your preferred environment, whether that's the [dbt Cloud CLI](/docs/cloud/cloud-cli-installation), [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud), or [dbt Core](/docs/core/installation-overview) - Use [MetricFlow commands](/docs/build/metricflow-commands) to query and test those metrics in your development environment - Harness the true magic of the universal dbt Semantic Layer and dynamically query these metrics in downstream tools (Available for dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) accounts only). -
-

- ## Related docs - [The dbt Semantic Layer: what's next](https://www.getdbt.com/blog/dbt-semantic-layer-whats-next/) blog - [Get started with MetricFlow](/docs/build/sl-getting-started) - - +- [dbt Semantic Layer on-demand courses](https://courses.getdbt.com/courses/semantic-layer) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index ec962969c9e..36002fd15a9 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -62,23 +62,23 @@ metrics: description: The cumulative value of all orders type: cumulative type_params: - fill_nulls_with: 0 measure: order_total + fill_nulls_with: 0 - name: cumulative_order_total_l1m label: Cumulative Order total (L1M) description: Trailing 1 month cumulative order amount type: cumulative type_params: - fills_nulls_with: 0 measure: order_total + fill_nulls_with: 0 window: 1 month - name: cumulative_order_total_mtd label: Cumulative Order total (MTD) description: The month to date value of all orders type: cumulative type_params: - fills_nulls_with: 0 measure: order_total + fill_nulls_with: 0 grain_to_date: month ``` diff --git a/website/docs/docs/build/derived-metrics.md b/website/docs/docs/build/derived-metrics.md index 35adb12cb1a..7e0b6115120 100644 --- a/website/docs/docs/build/derived-metrics.md +++ b/website/docs/docs/build/derived-metrics.md @@ -21,7 +21,6 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi | `metrics` | The list of metrics used in the derived metrics. | Required | | `alias` | Optional alias for the metric that you can use in the expr. | Optional | | `filter` | Optional filter to apply to the metric. | Optional | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | | `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Optional | The following displays the complete specification for derived metrics, along with an example. @@ -33,7 +32,6 @@ metrics: type: derived # Required label: The value that will be displayed in downstream tools #Required type_params: # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional expr: the derived expression # Required metrics: # The list of metrics used in the derived metrics # Required - name: the name of the metrics. must reference a metric you have already defined # Required @@ -51,7 +49,6 @@ metrics: type: derived label: Order Gross Profit type_params: - fill_nulls_with: 0 expr: revenue - cost metrics: - name: order_total @@ -63,7 +60,6 @@ metrics: description: "The gross profit for each food order." type: derived type_params: - fill_nulls_with: 0 expr: revenue - cost metrics: - name: order_total @@ -100,7 +96,6 @@ The following example displays how you can calculate monthly revenue growth usin description: Percentage of customers that are active now and those active 1 month ago label: customer_retention type_params: - fill_nulls_with: 0 expr: (active_customers/ active_customers_prev_month) metrics: - name: active_customers @@ -120,7 +115,6 @@ You can query any granularity and offset window combination. The following examp type: derived label: d7 Bookings Change type_params: - fill_nulls_with: 0 expr: bookings - bookings_7_days_ago metrics: - name: bookings diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index b5178076eda..82263775c28 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -21,7 +21,6 @@ The keys for metrics definitions are: | `label` | The display name for your metric. This value will be shown in downstream tools. | Required | | `filter` | You can optionally add a filter string to any metric type, applying filters to dimensions, entities, or time dimensions during metric computation. Consider it as your WHERE clause. | Optional | - Here's a complete example of the metrics spec configuration: ```yaml @@ -40,6 +39,10 @@ metrics: This page explains the different supported metric types you can add to your dbt project. +import SLCourses from '/snippets/_sl-course.md'; + + + ### Conversion metrics [Conversion metrics](/docs/build/conversion) help you track when a base event and a subsequent conversion event occurs for an entity within a set time period. diff --git a/website/docs/docs/build/ratio-metrics.md b/website/docs/docs/build/ratio-metrics.md index 5de4128c1f5..85b03821026 100644 --- a/website/docs/docs/build/ratio-metrics.md +++ b/website/docs/docs/build/ratio-metrics.md @@ -21,7 +21,6 @@ Ratio allows you to create a ratio between two metrics. You simply specify a num | `denominator` | The name of the metric used for the denominator, or structure of properties. | Required | | `filter` | Optional filter for the numerator or denominator. | Optional | | `alias` | Optional alias for the numerator or denominator. | Optional | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | The following displays the complete specification for ratio metrics, along with an example. @@ -32,7 +31,6 @@ metrics: type: ratio # Required label: The value that will be displayed in downstream tools #Required type_params: # Required - fill_nulls_with: Set value instead of null (such as zero) # Optional numerator: The name of the metric used for the numerator, or structure of properties # Required name: Name of metric used for the numerator # Required filter: Filter for the numerator # Optional @@ -52,7 +50,6 @@ metrics: label: Food Order Ratio type: ratio type_params: - fill_nulls_with: 0 numerator: food_orders denominator: orders ``` @@ -117,8 +114,7 @@ metrics: owners: - support@getdbt.com type: ratio - type_params: - fill_nulls_with: 0 + type_params:0 numerator: name: distinct_purchasers filter: | @@ -128,7 +124,7 @@ metrics: name: distinct_purchasers ``` -Note the `filter` and `alias` parameters for the metric referenced in the numerator. +Note the `filter` and `alias` parameters for the metric referenced in the numerator. - Use the `filter` parameter to apply a filter to the metric it's attached to. - The `alias` parameter is used to avoid naming conflicts in the rendered SQL queries when the same metric is used with different filters. - If there are no naming conflicts, the `alias` parameter can be left out. diff --git a/website/docs/docs/build/semantic-models.md b/website/docs/docs/build/semantic-models.md index afb877db504..472d1bd1f18 100644 --- a/website/docs/docs/build/semantic-models.md +++ b/website/docs/docs/build/semantic-models.md @@ -20,6 +20,11 @@ Semantic models are the foundation for data definition in MetricFlow, which powe +import SLCourses from '/snippets/_sl-course.md'; + + + + Here we describe the Semantic model components with examples: | Component | Description | Type | diff --git a/website/docs/docs/build/simple.md b/website/docs/docs/build/simple.md index fafb770dd04..7fe8e79bcf8 100644 --- a/website/docs/docs/build/simple.md +++ b/website/docs/docs/build/simple.md @@ -9,7 +9,7 @@ pagination_next: null Simple metrics are metrics that directly reference a single measure, without any additional measures involved. They are aggregations over a column in your data platform and can be filtered by one or multiple dimensions. - The parameters, description, and type for simple metrics are: + The parameters, description, and type for simple metrics are: | Parameter | Description | Type | | --------- | ----------- | ---- | @@ -20,6 +20,7 @@ Simple metrics are metrics that directly reference a single measure, without any | `type_params` | The type parameters of the metric. | Required | | `measure` | The measure you're referencing. | Required | | `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | +| `join_to_timespine` | Boolean that supports metric nodes with `true` or `false` options. | Optional | The following displays the complete specification for simple metrics, along with an example. @@ -52,15 +53,15 @@ If you've already defined the measure using the `create_metric: true` parameter, type: simple # Pointers to a measure you created in a semantic model label: Count of customers type_params: - fills_nulls_with: 0 measure: customers # The measure you're creating a proxy of. + fill_nulls_with: 0 - name: large_orders description: "Order with order values over 20." type: SIMPLE label: Large Orders type_params: - fill_nulls_with: 0 measure: orders + fill_nulls_with: 0 filter: | # For any metric you can optionally include a filter on dimension values {{Dimension('customer__order_total_dim')}} >= 20 ``` diff --git a/website/docs/docs/build/sl-getting-started.md b/website/docs/docs/build/sl-getting-started.md index 4274fccf509..082ed97ac18 100644 --- a/website/docs/docs/build/sl-getting-started.md +++ b/website/docs/docs/build/sl-getting-started.md @@ -30,6 +30,10 @@ MetricFlow allows you to define metrics in your dbt project and query them wheth However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account. +import SLCourses from '/snippets/_sl-course.md'; + + + ## Prerequisites import SetUp from '/snippets/_v2-sl-prerequisites.md'; diff --git a/website/docs/docs/use-dbt-semantic-layer/avail-sl-integrations.md b/website/docs/docs/use-dbt-semantic-layer/avail-sl-integrations.md index 8427a15cc11..88cc715e6c0 100644 --- a/website/docs/docs/use-dbt-semantic-layer/avail-sl-integrations.md +++ b/website/docs/docs/use-dbt-semantic-layer/avail-sl-integrations.md @@ -39,3 +39,4 @@ import AvailIntegrations from '/snippets/_sl-partner-links.md'; - [dbt Semantic Layer API query syntax](/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) - [Hex dbt Semantic Layer cells](https://learn.hex.tech/docs/logic-cell-types/transform-cells/dbt-metrics-cells) to set up SQL cells in Hex. - [Resolve 'Failed APN'](/faqs/Troubleshooting/sl-alpn-error) error when connecting to the dbt Semantic Layer. +- [dbt Semantic Layer on-demand courses](https://courses.getdbt.com/courses/semantic-layer) diff --git a/website/docs/docs/use-dbt-semantic-layer/gsheets.md b/website/docs/docs/use-dbt-semantic-layer/gsheets.md index d7525fa7b26..ff2e127a982 100644 --- a/website/docs/docs/use-dbt-semantic-layer/gsheets.md +++ b/website/docs/docs/use-dbt-semantic-layer/gsheets.md @@ -9,7 +9,7 @@ sidebar_label: "Google Sheets (beta)" Google Sheets integration with the dbt Semantic Layer is a [beta](/docs/dbt-versions/product-lifecycles#dbt-cloud) feature. ::: -The dbt Semantic Layer offers a seamless integration with Google Sheets through a custom menu. This add-on allows you to build dbt Semantic Layer queries and return data on your metrics directly within Google Sheet. +The dbt Semantic Layer offers a seamless integration with Google Sheets through a custom menu. This add-on allows you to build dbt Semantic Layer queries and return data on your metrics directly within Google Sheets. ## Prerequisites @@ -20,7 +20,11 @@ The dbt Semantic Layer offers a seamless integration with Google Sheets through - You must have a dbt Cloud Team or Enterprise [account](https://www.getdbt.com/pricing). Suitable for both Multi-tenant and Single-tenant deployment. - Single-tenant accounts should contact their account representative for necessary setup and enablement. -## Installing the add-on +import SLCourses from '/snippets/_sl-course.md'; + + + +## Installing the add-on 1. Navigate to the [dbt Semantic Layer for Sheets App](https://gsuite.google.com/marketplace/app/foo/392263010968) to install the add-on. diff --git a/website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md b/website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md index 11a610805a9..5942c820d33 100644 --- a/website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md +++ b/website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md @@ -23,8 +23,7 @@ import DeprecationNotice from '/snippets/_sl-deprecation-notice.md'; - -The dbt Semantic Layer, powered by [MetricFlow](/docs/build/about-metricflow), simplifies defining and using critical business metrics. It centralizes metric definitions, eliminates duplicate coding, and ensures consistent self-service access to metrics in downstream tools. +The dbt Semantic Layer, powered by [MetricFlow](/docs/build/about-metricflow), simplifies defining and using critical business metrics. It centralizes metric definitions, eliminates duplicate coding, and ensures consistent self-service access to metrics in downstream tools. MetricFlow, a powerful component of the dbt Semantic Layer, simplifies the creation and management of company metrics. It offers flexible abstractions, SQL query generation, and enables fast retrieval of metric datasets from a data platform. @@ -39,7 +38,11 @@ Use this guide to fully experience the power of the universal dbt Semantic Layer MetricFlow allows you to define metrics in your dbt project and query them whether in dbt Cloud or dbt Core with [MetricFlow commands](/docs/build/metricflow-commands). -However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account. +However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account. + +import SLCourses from '/snippets/_sl-course.md'; + + ## Prerequisites diff --git a/website/docs/docs/use-dbt-semantic-layer/setup-sl.md b/website/docs/docs/use-dbt-semantic-layer/setup-sl.md index 1016de1830a..b02e5d25d7a 100644 --- a/website/docs/docs/use-dbt-semantic-layer/setup-sl.md +++ b/website/docs/docs/use-dbt-semantic-layer/setup-sl.md @@ -23,6 +23,10 @@ import SetUp from '/snippets/_v2-sl-prerequisites.md'; +import SLCourses from '/snippets/_sl-course.md'; + + + ## Set up dbt Semantic Layer import SlSetUp from '/snippets/_new-sl-setup.md'; diff --git a/website/docs/docs/use-dbt-semantic-layer/tableau.md b/website/docs/docs/use-dbt-semantic-layer/tableau.md index 05d78f30f55..4f6d4f0d972 100644 --- a/website/docs/docs/use-dbt-semantic-layer/tableau.md +++ b/website/docs/docs/use-dbt-semantic-layer/tableau.md @@ -11,7 +11,7 @@ The Tableau integration with the dbt Semantic Layer is a [beta feature](/docs/db The Tableau integration allows you to use worksheets to query the Semantic Layer directly and produce your dashboards with trusted data. -This integration provides a live connection to the dbt Semantic Layer through Tableau Desktop or Tableau Server. +This integration provides a live connection to the dbt Semantic Layer through Tableau Desktop or Tableau Server. ## Prerequisites @@ -23,6 +23,10 @@ This integration provides a live connection to the dbt Semantic Layer through Ta - You must have a dbt Cloud Team or Enterprise [account](https://www.getdbt.com/pricing). Suitable for both Multi-tenant and Single-tenant deployment. - Single-tenant accounts should contact their account representative for necessary setup and enablement. +import SLCourses from '/snippets/_sl-course.md'; + + + ## Installing the Connector 1. Download the GitHub [connector file](https://github.com/dbt-labs/semantic-layer-tableau-connector/releases/download/v1.0.2/dbt_semantic_layer.taco) locally and add it to your default folder: diff --git a/website/docs/guides/sl-migration.md b/website/docs/guides/sl-migration.md index afa181646e3..31a06dfd534 100644 --- a/website/docs/guides/sl-migration.md +++ b/website/docs/guides/sl-migration.md @@ -136,3 +136,4 @@ If you created a new environment in [Step 3](#step-3-setup-the-semantic-layer-in - [dbt metrics converter](https://github.com/dbt-labs/dbt-converter) - [Why we're deprecating the dbt_metrics package](/blog/deprecating-dbt-metrics) blog post - [dbt Semantic Layer API query syntax](/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) +- [dbt Semantic Layer on-demand courses](https://courses.getdbt.com/courses/semantic-layer) diff --git a/website/docs/guides/sl-partner-integration-guide.md b/website/docs/guides/sl-partner-integration-guide.md index c55bd83cec1..e0678672dc9 100644 --- a/website/docs/guides/sl-partner-integration-guide.md +++ b/website/docs/guides/sl-partner-integration-guide.md @@ -17,6 +17,10 @@ To fit your tool within the world of the Semantic Layer, dbt Labs offers some be This is an evolving guide that is meant to provide recommendations based on our experience. If you have any feedback, we'd love to hear it! +import SLCourses from '/snippets/_sl-course.md'; + + + ### Prerequisites To build a dbt Semantic Layer integration: diff --git a/website/snippets/_sl-course.md b/website/snippets/_sl-course.md new file mode 100644 index 00000000000..d9df7afa9d2 --- /dev/null +++ b/website/snippets/_sl-course.md @@ -0,0 +1,8 @@ +
+📹 Discover dbt Semantic Layer on-demand video courses! + +Explore our [dbt Semantic Layer on-demand course](https://courses.getdbt.com/courses/semantic-layer) to learn how to define and query metrics in your dbt project. + +Additionally, dive into mini-courses for querying the dbt Semantic Layer in your favorite tools: [Tableau (beta)](https://courses.getdbt.com/courses/tableau-querying-the-semantic-layer), [Hex](https://courses.getdbt.com/courses/hex-querying-the-semantic-layer), and [Mode](https://courses.getdbt.com/courses/mode-querying-the-semantic-layer). + +
From 1c26f534527d1811fd5cc8e274ca04e1fb8dafe7 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 14 Feb 2024 11:52:02 +0000 Subject: [PATCH 02/19] updates --- website/docs/docs/build/about-metricflow.md | 71 +++++++++---------- website/docs/docs/build/conversion-metrics.md | 5 +- website/docs/docs/build/cumulative-metrics.md | 23 +++--- website/docs/docs/build/derived-metrics.md | 1 + website/docs/docs/build/metrics-overview.md | 34 ++++----- website/docs/docs/build/ratio-metrics.md | 5 +- website/docs/docs/build/simple.md | 12 ++-- 7 files changed, 80 insertions(+), 71 deletions(-) diff --git a/website/docs/docs/build/about-metricflow.md b/website/docs/docs/build/about-metricflow.md index 19d27bc60d2..6c6d8bd5ae1 100644 --- a/website/docs/docs/build/about-metricflow.md +++ b/website/docs/docs/build/about-metricflow.md @@ -245,43 +245,42 @@ metrics: ## FAQs -
- Do my datasets need to be normalized? -
-
Not at all! While a cleaned and well-modeled data set can be extraordinarily powerful and is the ideal input, you can use any dataset from raw to fully denormalized datasets.

It's recommended that you apply quality data consistency, such as filtering bad data, normalizing common objects, and data modeling of keys and tables, in upstream applications. The Semantic Layer is more efficient at doing data denormalization instead of normalization.

If you have not invested in data consistency, that is okay. The Semantic Layer can take SQL queries or expressions to define consistent datasets.
-
-
-
- Why is normalized data the ideal input? -
-
MetricFlow is built to do denormalization efficiently. There are better tools to take raw datasets and accomplish the various tasks required to build data consistency and organized data models. On the other end, by putting in denormalized data you are potentially creating redundancy which is technically challenging to manage, and you are reducing the potential granularity that MetricFlow can use to aggregate metrics.
-
-
-
- Why not just make metrics the same as measures? -
-
One principle of MetricFlow is to reduce the duplication of logic sometimes referred to as Don't Repeat Yourself(DRY).

Many metrics are constructed from reused measures and in some cases constructed from measures from different semantic models. This allows for metrics to be built breadth-first (metrics that can stand alone) instead of depth-first (where you have multiple metrics acting as functions of each other).

Additionally, not all metrics are constructed off of measures. As an example, a conversion metric is likely defined as the presence or absence of an event record after some other event record.
-
-
-
- How does the Semantic Layer handle joins? -
-
MetricFlow builds joins based on the types of keys and parameters that are passed to entities. To better understand how joins are constructed see our documentation on join types.

Rather than capturing arbitrary join logic, MetricFlow captures the types of each identifier and then helps the user to navigate to appropriate joins. This allows us to avoid the construction of fan out and chasm joins as well as generate legible SQL.
-
-
-
- Are entities and join keys the same thing? -
-
If it helps you to think of entities as join keys, that is very reasonable. Entities in MetricFlow have applications beyond joining two tables, such as acting as a dimension.
-
-
-
- Can a table without a primary or unique entities have dimensions? -
-
Yes, but because a dimension is considered an attribute of the primary or unique ent of the table, they are only usable by the metrics that are defined in that table. They cannot be joined to metrics from other tables. This is common in event logs.
-
-
+ +Not at all! While a cleaned and well-modeled data set can be extraordinarily powerful and is the ideal input, you can use any dataset from raw to fully denormalized datasets. + +It's recommended that you apply quality data consistency, such as filtering bad data, normalizing common objects, and data modeling of keys and tables, in upstream applications. The Semantic Layer is more efficient at doing data denormalization instead of normalization. + +If you have not invested in data consistency, that is okay. The Semantic Layer can take SQL queries or expressions to define consistent datasets. + + + + + +MetricFlow is built to do denormalization efficiently. There are better tools to take raw datasets and accomplish the various tasks required to build data consistency and organized data models. On the other end, by putting in denormalized data you are potentially creating redundancy which is technically challenging to manage, and you are reducing the potential granularity that MetricFlow can use to aggregate metrics. + + + +One principle of MetricFlow is to reduce the duplication of logic sometimes referred to as Don't Repeat Yourself(DRY). + +Many metrics are constructed from reused measures and in some cases constructed from measures from different semantic models. This allows for metrics to be built breadth-first (metrics that can stand alone) instead of depth-first (where you have multiple metrics acting as functions of each other). + +Additionally, not all metrics are constructed off of measures. As an example, a conversion metric is likely defined as the presence or absence of an event record after some other event record. + + + +The dbt Semantic Layer, powered by MetricFlow, builds joins based on the types of keys and parameters that are passed to entities. To better understand how joins are constructed see our documentation on join types. + +Rather than capturing arbitrary join logic, MetricFlow captures the types of each identifier and then helps the user to navigate to appropriate joins. This allows us to avoid the construction of fan out and chasm joins as well as generate legible SQL. + + + +If it helps you to think of entities as join keys, that is very reasonable. Entities in MetricFlow have applications beyond joining two tables, such as acting as a dimension. + + + +Yes, but because a dimension is considered an attribute of the primary or unique ent of the table, they are only usable by the metrics that are defined in that table. They cannot be joined to metrics from other tables. This is common in event logs. + ## Related docs - [Joins](/docs/build/join-logic) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 39b3d969b27..c2947893c6a 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -33,6 +33,7 @@ The specification for conversion metrics is as follows: | `base_property` | The property from the base semantic model that you want to hold constant. | Entity or Dimension | Optional | | `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Entity or Dimension | Optional | | `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | String | Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Refer to [additional settings](#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties. @@ -45,7 +46,7 @@ metrics: type: conversion # Required label: # Required type_params: # Required - fills_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional conversion_type_params: # Required entity: ENTITY # Required calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. @@ -93,7 +94,7 @@ Next, define a conversion metric as follows: type: conversion label: Visit to Buy Conversion Rate (7-day window) type_params: - fills_nulls_with: 0 + fill_nulls_with: 0 conversion_type_params: base_measure: visits conversion_measure: sellers diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 36002fd15a9..f02d3616b8c 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -21,6 +21,7 @@ This metric is common for calculating things like weekly active users, or month- | `window` | The accumulation window, such as 1 month, 7 days, 1 year. This can't be used with `grain_to_date`. | Optional | | `grain_to_date` | Sets the accumulation grain, such as month will accumulate data for one month. Then restart at the beginning of the next. This can't be used with `window`. | Optional | | `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero).| Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for cumulative metrics, along with an example: @@ -31,10 +32,11 @@ metrics: type: cumulative # Required label: The value that will be displayed in downstream tools # Required type_params: # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - measure: The measure you are referencing # Required - window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. Cannot be used with grain_to_date - grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. Cannot be used with window + measure: + name: The measure you are referencing # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. Cannot be used with grain_to_date + grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. Cannot be used with window ``` @@ -62,24 +64,27 @@ metrics: description: The cumulative value of all orders type: cumulative type_params: - measure: order_total + measure: + name: order_total fill_nulls_with: 0 - name: cumulative_order_total_l1m label: Cumulative Order total (L1M) description: Trailing 1 month cumulative order amount type: cumulative type_params: - measure: order_total + measure: + name: order_total fill_nulls_with: 0 - window: 1 month + window: 1 month - name: cumulative_order_total_mtd label: Cumulative Order total (MTD) description: The month to date value of all orders type: cumulative type_params: - measure: order_total + measure: + name: order_total fill_nulls_with: 0 - grain_to_date: month + grain_to_date: month ``` ### Window options diff --git a/website/docs/docs/build/derived-metrics.md b/website/docs/docs/build/derived-metrics.md index 7e0b6115120..f41218a2b1b 100644 --- a/website/docs/docs/build/derived-metrics.md +++ b/website/docs/docs/build/derived-metrics.md @@ -22,6 +22,7 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi | `alias` | Optional alias for the metric that you can use in the expr. | Optional | | `filter` | Optional filter to apply to the metric. | Optional | | `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for derived metrics, along with an example. diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index 82263775c28..3191869e96b 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -20,6 +20,8 @@ The keys for metrics definitions are: | `config` | Provide the specific configurations for your metric. | Optional | | `label` | The display name for your metric. This value will be shown in downstream tools. | Required | | `filter` | You can optionally add a filter string to any metric type, applying filters to dimensions, entities, or time dimensions during metric computation. Consider it as your WHERE clause. | Optional | +| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero).| Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Here's a complete example of the metrics spec configuration: @@ -54,7 +56,7 @@ metrics: type: conversion # Required label: # Required type_params: # Required - fills_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional conversion_type_params: # Required entity: ENTITY # Required calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. @@ -78,11 +80,13 @@ metrics: - support@getdbt.com type: cumulative type_params: - fills_nulls_with: 0 - measures: - - distinct_users - # Omitting window will accumulate the measure over all time - window: 7 days + measure: + name: active_users + fill_nulls_with: 0 + measure: + name: distinct_users + # Omitting window will accumulate the measure over all time + window: 7 days ``` @@ -97,7 +101,6 @@ metrics: type: derived label: Order Gross Profit type_params: - fills_nulls_with: 0 expr: revenue - cost metrics: - name: order_total @@ -137,7 +140,6 @@ metrics: # Define the metrics from the semantic manifest as numerator or denominator type: ratio type_params: - fills_nulls_with: 0 numerator: cancellations denominator: transaction_amount filter: | # add optional constraint string. This applies to both the numerator and denominator @@ -171,15 +173,17 @@ metrics: - name: cancellations type: simple type_params: - fills_nulls_with: 0 - measure: cancellations_usd # Specify the measure you are creating a proxy for. - filter: | - {{ Dimension('order__value')}} > 100 and {{Dimension('user__acquisition')}} + measure: + name: cancellations_usd # Specify the measure you are creating a proxy for. + fill_nulls_with: 0 + filter: | + {{ Dimension('order__value')}} > 100 and {{Dimension('user__acquisition')}} ``` ## Filters A filter is configured using Jinja templating. Use the following syntax to reference entities, dimensions, and time dimensions in filters: + ```yaml filter: | {{ Entity('entity_name') }} @@ -189,7 +193,7 @@ filter: | {{ TimeDimension('time_dimension', 'granularity') }} ``` -### Further configuration +### Further configuration You can set more metadata for your metrics, which can be used by other tools later on. The way this metadata is used will vary based on the specific integration partner @@ -200,7 +204,3 @@ You can set more metadata for your metrics, which can be used by other tools lat - [Semantic models](/docs/build/semantic-models) - [Cumulative](/docs/build/cumulative) - [Derived](/docs/build/derived) - - - - diff --git a/website/docs/docs/build/ratio-metrics.md b/website/docs/docs/build/ratio-metrics.md index 85b03821026..ed4ccf95f39 100644 --- a/website/docs/docs/build/ratio-metrics.md +++ b/website/docs/docs/build/ratio-metrics.md @@ -21,6 +21,7 @@ Ratio allows you to create a ratio between two metrics. You simply specify a num | `denominator` | The name of the metric used for the denominator, or structure of properties. | Required | | `filter` | Optional filter for the numerator or denominator. | Optional | | `alias` | Optional alias for the numerator or denominator. | Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for ratio metrics, along with an example. @@ -114,7 +115,7 @@ metrics: owners: - support@getdbt.com type: ratio - type_params:0 + type_params: numerator: name: distinct_purchasers filter: | @@ -124,7 +125,7 @@ metrics: name: distinct_purchasers ``` -Note the `filter` and `alias` parameters for the metric referenced in the numerator. +Note the `filter` and `alias` parameters for the metric referenced in the numerator. - Use the `filter` parameter to apply a filter to the metric it's attached to. - The `alias` parameter is used to avoid naming conflicts in the rendered SQL queries when the same metric is used with different filters. - If there are no naming conflicts, the `alias` parameter can be left out. diff --git a/website/docs/docs/build/simple.md b/website/docs/docs/build/simple.md index 7fe8e79bcf8..9f32cbf0906 100644 --- a/website/docs/docs/build/simple.md +++ b/website/docs/docs/build/simple.md @@ -20,11 +20,10 @@ Simple metrics are metrics that directly reference a single measure, without any | `type_params` | The type parameters of the metric. | Required | | `measure` | The measure you're referencing. | Required | | `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | -| `join_to_timespine` | Boolean that supports metric nodes with `true` or `false` options. | Optional | +| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for simple metrics, along with an example. - ```yaml metrics: - name: The metric name # Required @@ -33,7 +32,8 @@ metrics: label: The value that will be displayed in downstream tools # Required type_params: # Required measure: The measure you're referencing # Required - fill_nulls_with: Set value instead of null (such as zero) # Optional + name: Name of your measure # Required + fill_nulls_with: Set value instead of null (such as zero) # Optional ``` @@ -53,14 +53,16 @@ If you've already defined the measure using the `create_metric: true` parameter, type: simple # Pointers to a measure you created in a semantic model label: Count of customers type_params: - measure: customers # The measure you're creating a proxy of. + measure: + name: customers # The measure you're creating a proxy of. fill_nulls_with: 0 - name: large_orders description: "Order with order values over 20." type: SIMPLE label: Large Orders type_params: - measure: orders + measure: + name: orders fill_nulls_with: 0 filter: | # For any metric you can optionally include a filter on dimension values {{Dimension('customer__order_total_dim')}} >= 20 From a1451797c944ed6698477d1b3f562f3d501b2d72 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 14 Feb 2024 11:57:32 +0000 Subject: [PATCH 03/19] Update gsheets.md --- website/docs/docs/use-dbt-semantic-layer/gsheets.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/docs/use-dbt-semantic-layer/gsheets.md b/website/docs/docs/use-dbt-semantic-layer/gsheets.md index b4cbc322924..54f2892b580 100644 --- a/website/docs/docs/use-dbt-semantic-layer/gsheets.md +++ b/website/docs/docs/use-dbt-semantic-layer/gsheets.md @@ -29,7 +29,7 @@ import SLCourses from '/snippets/_sl-course.md'; ## Installing the add-on 1. Navigate to the [dbt Semantic Layer for Sheets App](https://gsuite.google.com/marketplace/app/foo/392263010968) to install the add-on. You can also find it in Google Sheets by going to [**Extensions -> Add-on -> Get add-ons**](https://support.google.com/docs/answer/2942256?hl=en&co=GENIE.Platform%3DDesktop&oco=0#zippy=%2Cinstall-add-ons%2Cinstall-an-add-on) and searching for it there. -2. After installing, open the Add-On menu and select the "dbt Semantic Layer for Sheets". This will open a custom menu to the right-hand side of your screen. +2. After installing, open the Add-On menu and select the "dbt Semantic Layer for Sheets". This will open a custom menu on the right-hand side of your screen. 3. Find your **Host** and **Environment ID** in dbt Cloud. Navigate to **Account Settings** and select **Projects** on the left sidebar. Select your project and then navigate to the **Semantic Layer** settings. You'll need this to authenticate in Google Sheets in the following step. - You can [generate your service token](/docs/dbt-cloud-apis/service-tokens) by clicking **Generate Service Token** within the Semantic Layer configuration page or navigating to **API tokens** in dbt Cloud. @@ -54,17 +54,17 @@ The custom menu provides the following capabilities: | Group By | Search and select dimensions to group by. Dimensions are grouped by the entity of the semantic model they come from. | | Granularity | Modify the granularity of the primary time dimension. | | Where | Filter your data. This includes categorical and time filters. | -| Order By | Return your data ordered. | +| Order By | Return your data order. | | Limit | Set a limit for the rows of your output. | ## Filtering data To use the filter functionality, choose the [dimension](docs/build/dimensions) you want to filter by and select the operation you want to filter on. - - For categorical dimensiosn, type in the dimension value you want to filter by (no quotes needed) and press enter. + - For categorical dimensions, type in the dimension value you want to filter by (no quotes needed) and press enter. - Continue adding additional filters as needed with AND and OR. If it's a time dimension, choose the operator and select from the calendar. -**Limited Use Policy Disclosure** +**Limited use policy disclosure** The dbt Semantic Layer for Sheet's use and transfer to any other app of information received from Google APIs will adhere to [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements. From 673c3d4615666b4b109c2e98796f187b828f0bf2 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 14 Feb 2024 12:02:53 +0000 Subject: [PATCH 04/19] Update simple.md --- website/docs/docs/build/simple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/simple.md b/website/docs/docs/build/simple.md index 9f32cbf0906..5104bf7d59f 100644 --- a/website/docs/docs/build/simple.md +++ b/website/docs/docs/build/simple.md @@ -40,7 +40,7 @@ metrics: From e1cb373c521760b42e596fb43fc1b5e85861a4da Mon Sep 17 00:00:00 2001 From: Jordan Stein Date: Fri, 16 Feb 2024 16:01:51 -0800 Subject: [PATCH 05/19] update fill_nulls_with and add_to_time_spine --- website/docs/docs/build/conversion-metrics.md | 22 +++++++++---- website/docs/docs/build/cumulative-metrics.md | 32 ++++++++----------- website/docs/docs/build/derived-metrics.md | 1 - website/docs/docs/build/ratio-metrics.md | 1 - website/docs/docs/build/simple.md | 18 ++++++----- 5 files changed, 40 insertions(+), 34 deletions(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index c2947893c6a..716be76542d 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -26,13 +26,18 @@ The specification for conversion metrics is as follows: | `conversion_type_params` | Additional configuration specific to conversion metrics. | List | Required | | `entity` | The entity for each conversion event. | Entity | Required | | `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | String | Optional | -| `base_measure` | The base conversion event measure. | Measure | Required | -| `conversion_measure` | The conversion event measure. | Measure | Required | +| `base_measure` | A list of base measure inputs | Measure | Required | +| `base_measure:name` | The base conversion event measure. | Measure | Required | +| `base_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | +| `base_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | +| `conversion_measure` | A list of conversion measure inputs | Measure | Required | +| `conversion_measure:name` | The base conversion event measure. | Measure | Required | +| `conversion_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | +| `conversion_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | | `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | String | Optional | | `constant_properties` | List of constant properties. | List | Optional | | `base_property` | The property from the base semantic model that you want to hold constant. | Entity or Dimension | Optional | | `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Entity or Dimension | Optional | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | String | Optional | | `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Refer to [additional settings](#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties. @@ -46,12 +51,17 @@ metrics: type: conversion # Required label: # Required type_params: # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional conversion_type_params: # Required entity: ENTITY # Required calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. - base_measure: MEASURE # Required - conversion_measure: MEASURE # Required + base_measure: + name: The name of the measure # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + conversion_measure: + name: The name of the measure # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional window: TIME_WINDOW # Optional. default: infinity. window to join the two events. Follows a similar format as time windows elsewhere (such as 7 days) constant_properties: # Optional. List of constant properties default: None - base_property: DIMENSION or ENTITY # Required. A reference to a dimension/entity of the semantic model linked to the base_measure diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index f02d3616b8c..83ecbf26bc7 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -17,11 +17,12 @@ This metric is common for calculating things like weekly active users, or month- | `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required | | `label` | The value that will be displayed in downstream tools. | Required | | `type_params` | The type parameters of the metric. | Required | -| `measure` | The measure you are referencing. | Required | | `window` | The accumulation window, such as 1 month, 7 days, 1 year. This can't be used with `grain_to_date`. | Optional | | `grain_to_date` | Sets the accumulation grain, such as month will accumulate data for one month. Then restart at the beginning of the next. This can't be used with `window`. | Optional | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero).| Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | +| `measure` | A list of measure inputs | Required | +| `measure:name` | TThe measure you are referencing. | Optional | +| `measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero).| Optional | +| `measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for cumulative metrics, along with an example: @@ -35,25 +36,16 @@ metrics: measure: name: The measure you are referencing # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. Cannot be used with grain_to_date - grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. Cannot be used with window + join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. Cannot be used with grain_to_date + grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. Cannot be used with windo ``` -## Limitations -Cumulative metrics are currently under active development and have the following limitations: -- You are required to use [`metric_time` dimension](/docs/build/dimensions#time) when querying 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. ## Cumulative metrics example - -:::tip MetricFlow time spine required - -You will need to create the [time spine model](/docs/build/metricflow-time-spine) before you add cumulative metrics. - -::: - Cumulative metrics measure data over a given window and consider the window infinite when no window parameter is passed, accumulating the data over all time. ```yaml @@ -75,7 +67,7 @@ metrics: measure: name: order_total fill_nulls_with: 0 - window: 1 month + window: 1 month - name: cumulative_order_total_mtd label: Cumulative Order total (MTD) description: The month to date value of all orders @@ -84,7 +76,7 @@ metrics: measure: name: order_total fill_nulls_with: 0 - grain_to_date: month + grain_to_date: month ``` ### Window options @@ -208,7 +200,7 @@ metrics: ### Implementation -The current method connects the metric table to a timespine table using the primary time dimension as the join key. We use the accumulation window in the join to decide whether a record should be included on a particular day. The following SQL code produced from an example cumulative metric is provided for reference: +To calculate the cumulative value of the metric over a given window we do a time range join to a timespine table using the primary time dimension as the join key. We use the accumulation window in the join to decide whether a record should be included on a particular day. The following SQL code produced from an example cumulative metric is provided for reference: ``` sql select @@ -256,3 +248,7 @@ group by limit 100; ``` +## Limitations + +Cumulative metrics have the following limitations: +- If you specify a window in your cumulatve metric definiton then you must include metric_time as a dimension in the query. This is because the accumulation window is based of of metric time. \ No newline at end of file diff --git a/website/docs/docs/build/derived-metrics.md b/website/docs/docs/build/derived-metrics.md index f41218a2b1b..7e0b6115120 100644 --- a/website/docs/docs/build/derived-metrics.md +++ b/website/docs/docs/build/derived-metrics.md @@ -22,7 +22,6 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi | `alias` | Optional alias for the metric that you can use in the expr. | Optional | | `filter` | Optional filter to apply to the metric. | Optional | | `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for derived metrics, along with an example. diff --git a/website/docs/docs/build/ratio-metrics.md b/website/docs/docs/build/ratio-metrics.md index ed4ccf95f39..ba97ca899ea 100644 --- a/website/docs/docs/build/ratio-metrics.md +++ b/website/docs/docs/build/ratio-metrics.md @@ -21,7 +21,6 @@ Ratio allows you to create a ratio between two metrics. You simply specify a num | `denominator` | The name of the metric used for the denominator, or structure of properties. | Required | | `filter` | Optional filter for the numerator or denominator. | Optional | | `alias` | Optional alias for the numerator or denominator. | Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for ratio metrics, along with an example. diff --git a/website/docs/docs/build/simple.md b/website/docs/docs/build/simple.md index 5104bf7d59f..46fc625d3ff 100644 --- a/website/docs/docs/build/simple.md +++ b/website/docs/docs/build/simple.md @@ -18,9 +18,10 @@ Simple metrics are metrics that directly reference a single measure, without any | `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required | | `label` | The value that will be displayed in downstream tools. | Required | | `type_params` | The type parameters of the metric. | Required | -| `measure` | The measure you're referencing. | Required | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | +| `measure` | A list of measure inputs | Required | +| `measure:name` | The measure you're referencing. | Required | +| `measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | +| `mesure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for simple metrics, along with an example. @@ -31,9 +32,10 @@ metrics: type: simple # Required label: The value that will be displayed in downstream tools # Required type_params: # Required - measure: The measure you're referencing # Required - name: Name of your measure # Required + measure: + name: The name of your measure # Required fill_nulls_with: Set value instead of null (such as zero) # Optional + join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. #Optinal ``` @@ -54,8 +56,9 @@ If you've already defined the measure using the `create_metric: true` parameter, label: Count of customers type_params: measure: - name: customers # The measure you're creating a proxy of. - fill_nulls_with: 0 + name: customers # The measure you are creating a proxy of. + fill_nulls_with: 0 + join_to_timespine: true - name: large_orders description: "Order with order values over 20." type: SIMPLE @@ -63,7 +66,6 @@ If you've already defined the measure using the `create_metric: true` parameter, type_params: measure: name: orders - fill_nulls_with: 0 filter: | # For any metric you can optionally include a filter on dimension values {{Dimension('customer__order_total_dim')}} >= 20 ``` From 4f1f3f7f386bd0f9f999b236af3a3490ba6aa741 Mon Sep 17 00:00:00 2001 From: Jordan Stein Date: Fri, 16 Feb 2024 16:06:56 -0800 Subject: [PATCH 06/19] remove join_to_timespine --- website/docs/docs/build/conversion-metrics.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 716be76542d..2b7f529f007 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -38,7 +38,6 @@ The specification for conversion metrics is as follows: | `constant_properties` | List of constant properties. | List | Optional | | `base_property` | The property from the base semantic model that you want to hold constant. | Entity or Dimension | Optional | | `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Entity or Dimension | Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Refer to [additional settings](#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties. From 3aff58ca67e7db7ac8564695f1528968f54215d5 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 19 Feb 2024 09:31:19 +0000 Subject: [PATCH 07/19] Update conversion-metrics.md --- website/docs/docs/build/conversion-metrics.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 2b7f529f007..470efc1baa5 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -16,28 +16,28 @@ Conversion metrics are different from [ratio metrics](/docs/build/ratio) because The specification for conversion metrics is as follows: -| Parameter | Description | Type | Required/Optional | +| Parameter | Description | Required/Optional | | --- | --- | --- | --- | -| `name` | The name of the metric. | String | Required | -| `description` | The description of the metric. | String | Optional | -| `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion' | String | Required | -| `label` | Displayed value in downstream tools. | String | Required | -| `type_params` | Specific configurations for each metric type. | List | Required | -| `conversion_type_params` | Additional configuration specific to conversion metrics. | List | Required | +| `name` | The name of the metric. | Required | +| `description` | The description of the metric. | Optional | +| `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion' | Required | +| `label` | Displayed value in downstream tools. | Required | +| `type_params` | Specific configurations for each metric type. | Required | +| `conversion_type_params` | Additional configuration specific to conversion metrics. | Required | | `entity` | The entity for each conversion event. | Entity | Required | -| `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | String | Optional | -| `base_measure` | A list of base measure inputs | Measure | Required | -| `base_measure:name` | The base conversion event measure. | Measure | Required | +| `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | Optional | +| `base_measure` | A list of base measure inputs | Required | +| `base_measure:name` | The base conversion event measure. | Required | | `base_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | | `base_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | -| `conversion_measure` | A list of conversion measure inputs | Measure | Required | -| `conversion_measure:name` | The base conversion event measure. | Measure | Required | +| `conversion_measure` | A list of conversion measure inputs. | Required | +| `conversion_measure:name` | The base conversion event measure.| Required | | `conversion_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | | `conversion_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | -| `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | String | Optional | -| `constant_properties` | List of constant properties. | List | Optional | -| `base_property` | The property from the base semantic model that you want to hold constant. | Entity or Dimension | Optional | -| `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Entity or Dimension | Optional | +| `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | Optional | +| `constant_properties` | List of constant properties. | Optional | +| `base_property` | The property from the base semantic model that you want to hold constant. | Optional | +| `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Optional | Refer to [additional settings](#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties. @@ -48,7 +48,7 @@ metrics: - name: The metric name # Required description: The metric description # Optional type: conversion # Required - label: # Required + label: YOUR_LABEL # Required type_params: # Required conversion_type_params: # Required entity: ENTITY # Required From c32ca901c3899d0a479c9615d25f9e4545bf3d67 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 19 Feb 2024 09:32:09 +0000 Subject: [PATCH 08/19] Update website/docs/docs/build/conversion-metrics.md --- website/docs/docs/build/conversion-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 470efc1baa5..82046a80f89 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -16,7 +16,7 @@ Conversion metrics are different from [ratio metrics](/docs/build/ratio) because The specification for conversion metrics is as follows: -| Parameter | Description | Required/Optional | +| Parameter | Description | Type | | --- | --- | --- | --- | | `name` | The name of the metric. | Required | | `description` | The description of the metric. | Optional | From bd77b3b1c39c7dc37565e9fedf85bfb7b1d6b7da Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 19 Feb 2024 09:35:43 +0000 Subject: [PATCH 09/19] Update cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 83ecbf26bc7..66885f4d177 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -34,11 +34,11 @@ metrics: label: The value that will be displayed in downstream tools # Required type_params: # Required measure: - name: The measure you are referencing # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional - window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. Cannot be used with grain_to_date - grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. Cannot be used with windo + name: The measure you are referencing. # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero). # Optional + join_to_timespine: false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. It cannot be used with grain_to_date. + grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. It cannot be used with window. ``` @@ -52,7 +52,7 @@ Cumulative metrics measure data over a given window and consider the window infi metrics: - name: cumulative_order_total - label: Cumulative Order total (All Time) + label: Cumulative Order total (All-Time) description: The cumulative value of all orders type: cumulative type_params: @@ -61,7 +61,7 @@ metrics: fill_nulls_with: 0 - name: cumulative_order_total_l1m label: Cumulative Order total (L1M) - description: Trailing 1 month cumulative order amount + description: Trailing 1-month cumulative order amount type: cumulative type_params: measure: @@ -70,7 +70,7 @@ metrics: window: 1 month - name: cumulative_order_total_mtd label: Cumulative Order total (MTD) - description: The month to date value of all orders + description: The month-to-date value of all orders type: cumulative type_params: measure: @@ -184,14 +184,14 @@ We can compare the difference between a 1-month window and a monthly grain to da metrics: - name: cumulative_order_total_l1m #For this metric, we use a window of 1 month label: Cumulative Order total (L1M) - description: Trailing 1 month cumulative order amount + description: Trailing 1-month cumulative order amount type: cumulative type_params: measure: order_total window: 1 month - - name: cumulative_order_total_mtd #For this metric, we use a monthly grain to date + - name: cumulative_order_total_mtd #For this metric, we use a monthly grain-to-date label: Cumulative Order total (MTD) - description: The month to date value of all orders + description: The month-to-date value of all orders type: cumulative type_params: measure: order_total @@ -251,4 +251,4 @@ limit 100; ## Limitations Cumulative metrics have the following limitations: -- If you specify a window in your cumulatve metric definiton then you must include metric_time as a dimension in the query. This is because the accumulation window is based of of metric time. \ No newline at end of file +- If you specify a window in your cumulatve metric definiton then you must include metric_time as a dimension in the query. This is because the accumulation window is based of of metric time. From 53bfc0ffa4095038ad760b387b93751050394e5d Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 19 Feb 2024 09:50:59 +0000 Subject: [PATCH 10/19] Update cumulative-metrics.md --- website/docs/docs/build/cumulative-metrics.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index 66885f4d177..e1cf22a60fa 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -42,8 +42,6 @@ metrics: ``` - - ## Cumulative metrics example Cumulative metrics measure data over a given window and consider the window infinite when no window parameter is passed, accumulating the data over all time. @@ -250,5 +248,17 @@ limit 100; ``` ## Limitations -Cumulative metrics have the following limitations: -- If you specify a window in your cumulatve metric definiton then you must include metric_time as a dimension in the query. This is because the accumulation window is based of of metric time. +If you specify a `window` in your cumulatve metric definition, you must include `metric_time` as a dimension in the SQL query. This is because the accumulation window is based on metric time. For example, + +```sql +select + count(distinct subq_3.distinct_users) as weekly_active_users, + subq_3.metric_time +from ( + select + subq_2.distinct_users as distinct_users, + subq_1.metric_time as metric_time +group by + subq_3.metric_time +``` + From 2422fd56291765283bd8b034b33ac6c142d15aeb Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Mon, 19 Feb 2024 10:11:27 +0000 Subject: [PATCH 11/19] Update website/snippets/_sl-course.md --- website/snippets/_sl-course.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/snippets/_sl-course.md b/website/snippets/_sl-course.md index d9df7afa9d2..b06ed510bc1 100644 --- a/website/snippets/_sl-course.md +++ b/website/snippets/_sl-course.md @@ -1,5 +1,5 @@
-📹 Discover dbt Semantic Layer on-demand video courses! +📹 Learn about the dbt Semantic Layer with on-demand video courses! Explore our [dbt Semantic Layer on-demand course](https://courses.getdbt.com/courses/semantic-layer) to learn how to define and query metrics in your dbt project. From daa67b267712c538ed2652800275437c07ca8ee4 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 21 Feb 2024 12:21:29 +0000 Subject: [PATCH 12/19] fix spec --- website/docs/docs/build/conversion-metrics.md | 8 ++++--- website/docs/docs/build/cumulative-metrics.md | 2 +- website/docs/docs/build/metrics-overview.md | 24 ++++++++++++------- website/docs/docs/build/simple.md | 5 ++-- 4 files changed, 24 insertions(+), 15 deletions(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 82046a80f89..7e11c93023a 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -56,11 +56,11 @@ metrics: base_measure: name: The name of the measure # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional conversion_measure: name: The name of the measure # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional window: TIME_WINDOW # Optional. default: infinity. window to join the two events. Follows a similar format as time windows elsewhere (such as 7 days) constant_properties: # Optional. List of constant properties default: None - base_property: DIMENSION or ENTITY # Required. A reference to a dimension/entity of the semantic model linked to the base_measure @@ -103,10 +103,12 @@ Next, define a conversion metric as follows: type: conversion label: Visit to Buy Conversion Rate (7-day window) type_params: - fill_nulls_with: 0 conversion_type_params: base_measure: visits + name: visits + fill_nulls_with: 0 conversion_measure: sellers + name: sellers entity: user window: 7 days ``` diff --git a/website/docs/docs/build/cumulative-metrics.md b/website/docs/docs/build/cumulative-metrics.md index e1cf22a60fa..42ba056a66c 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -36,7 +36,7 @@ metrics: measure: name: The measure you are referencing. # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero). # Optional - join_to_timespine: false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional window: The accumulation window, such as 1 month, 7 days, 1 year. # Optional. It cannot be used with grain_to_date. grain_to_date: Sets the accumulation grain, such as month will accumulate data for one month, then restart at the beginning of the next. # Optional. It cannot be used with window. diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index 3191869e96b..6ba366aa876 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -20,8 +20,6 @@ The keys for metrics definitions are: | `config` | Provide the specific configurations for your metric. | Optional | | `label` | The display name for your metric. This value will be shown in downstream tools. | Required | | `filter` | You can optionally add a filter string to any metric type, applying filters to dimensions, entities, or time dimensions during metric computation. Consider it as your WHERE clause. | Optional | -| `fill_nulls_with` | Set the value in your metric definition instead of null (such as zero).| Optional | -| `join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Here's a complete example of the metrics spec configuration: @@ -54,14 +52,19 @@ metrics: - name: The metric name # Required description: The metric description # Optional type: conversion # Required - label: # Required + label: YOUR_LABEL # Required type_params: # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional conversion_type_params: # Required entity: ENTITY # Required calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. - base_measure: MEASURE # Required - conversion_measure: MEASURE # Required + base_measure: + name: The name of the measure # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + conversion_measure: + name: The name of the measure # Required + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional window: TIME_WINDOW # Optional. default: infinity. window to join the two events. Follows a similar format as time windows elsewhere (such as 7 days) constant_properties: # Optional. List of constant properties default: None - base_property: DIMENSION or ENTITY # Required. A reference to a dimension/entity of the semantic model linked to the base_measure @@ -79,10 +82,12 @@ metrics: owners: - support@getdbt.com type: cumulative + label: Weekly Active Users type_params: measure: name: active_users fill_nulls_with: 0 + join_to_timespine: true measure: name: distinct_users # Omitting window will accumulate the measure over all time @@ -128,10 +133,9 @@ metrics: ### Ratio metrics -[Ratio metrics](/docs/build/ratio) involve a numerator metric and a denominator metric. A `constraint` string can be applied to both the numerator and denominator or separately to the numerator or denominator. +[Ratio metrics](/docs/build/ratio) involve a numerator metric and a denominator metric. A `constraint` string can be applied to both the numerator and denominator or separately to the numerator or denominator. ```yaml -# Ratio Metric metrics: - name: cancellation_rate owners: @@ -139,6 +143,7 @@ metrics: # Ratio metrics create a ratio out of two metrics. # Define the metrics from the semantic manifest as numerator or denominator type: ratio + label: Cancellation rate type_params: numerator: cancellations denominator: transaction_amount @@ -171,13 +176,16 @@ metrics: ```yaml metrics: - name: cancellations + description: The number of cancellations type: simple + label: Cancellations type_params: measure: name: cancellations_usd # Specify the measure you are creating a proxy for. fill_nulls_with: 0 filter: | {{ Dimension('order__value')}} > 100 and {{Dimension('user__acquisition')}} + join_to_timespine: true ``` ## Filters diff --git a/website/docs/docs/build/simple.md b/website/docs/docs/build/simple.md index 46fc625d3ff..b9452cccc0b 100644 --- a/website/docs/docs/build/simple.md +++ b/website/docs/docs/build/simple.md @@ -21,7 +21,7 @@ Simple metrics are metrics that directly reference a single measure, without any | `measure` | A list of measure inputs | Required | | `measure:name` | The measure you're referencing. | Required | | `measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | -| `mesure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | +| `measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | The following displays the complete specification for simple metrics, along with an example. @@ -35,7 +35,7 @@ metrics: measure: name: The name of your measure # Required fill_nulls_with: Set value instead of null (such as zero) # Optional - join_to_timespine: Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. #Optinal + join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. # Optional ``` @@ -69,4 +69,3 @@ If you've already defined the measure using the `create_metric: true` parameter, filter: | # For any metric you can optionally include a filter on dimension values {{Dimension('customer__order_total_dim')}} >= 20 ``` - From af64fb2a7f7d997fa45a77d2cc0f03bd72baac90 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 21 Feb 2024 12:26:02 +0000 Subject: [PATCH 13/19] fix table --- website/docs/docs/build/conversion-metrics.md | 4 +- website/docs/docs/build/metrics-overview.md | 47 +++++++++---------- 2 files changed, 23 insertions(+), 28 deletions(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 7e11c93023a..9e832060df9 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -17,14 +17,14 @@ Conversion metrics are different from [ratio metrics](/docs/build/ratio) because The specification for conversion metrics is as follows: | Parameter | Description | Type | -| --- | --- | --- | --- | +| --- | --- | --- | | `name` | The name of the metric. | Required | | `description` | The description of the metric. | Optional | | `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion' | Required | | `label` | Displayed value in downstream tools. | Required | | `type_params` | Specific configurations for each metric type. | Required | | `conversion_type_params` | Additional configuration specific to conversion metrics. | Required | -| `entity` | The entity for each conversion event. | Entity | Required | +| `entity` | The entity for each conversion event. | Required | | `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | Optional | | `base_measure` | A list of base measure inputs | Required | | `base_measure:name` | The base conversion event measure. | Required | diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index 6ba366aa876..ce30da8ca89 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -49,26 +49,26 @@ import SLCourses from '/snippets/_sl-course.md'; ```yaml metrics: - - name: The metric name # Required - description: The metric description # Optional - type: conversion # Required - label: YOUR_LABEL # Required - type_params: # Required - conversion_type_params: # Required - entity: ENTITY # Required - calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. + - name: The metric name + description: The metric description + type: conversion + label: YOUR_LABEL + type_params: # + conversion_type_params: + entity: ENTITY + calculation: CALCULATION_TYPE base_measure: - name: The name of the measure # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional + name: The name of the measure + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) + join_to_timespine: true/false conversion_measure: - name: The name of the measure # Required - fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional - join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional - window: TIME_WINDOW # Optional. default: infinity. window to join the two events. Follows a similar format as time windows elsewhere (such as 7 days) - constant_properties: # Optional. List of constant properties default: None - - base_property: DIMENSION or ENTITY # Required. A reference to a dimension/entity of the semantic model linked to the base_measure - conversion_property: DIMENSION or ENTITY # Same as base above, but to the semantic model of the conversion_measure + name: The name of the measure + fill_nulls_with: Set the value in your metric definition instead of null (such as zero) + join_to_timespine: true/false + window: TIME_WINDOW + constant_properties: + - base_property: DIMENSION or ENTITY + conversion_property: DIMENSION or ENTITY ``` ### Cumulative metrics @@ -90,7 +90,6 @@ metrics: join_to_timespine: true measure: name: distinct_users - # Omitting window will accumulate the measure over all time window: 7 days ``` @@ -140,27 +139,23 @@ metrics: - name: cancellation_rate owners: - support@getdbt.com -# Ratio metrics create a ratio out of two metrics. -# Define the metrics from the semantic manifest as numerator or denominator type: ratio label: Cancellation rate type_params: numerator: cancellations denominator: transaction_amount - filter: | # add optional constraint string. This applies to both the numerator and denominator + filter: | {{ Dimension('customer__country') }} = 'MX' - name: enterprise_cancellation_rate owners: - support@getdbt.com - # Ratio metrics create a ratio out of two measures. - # Define the metrics from the semantic model as numerator or denominator type: ratio type_params: numerator: name: cancellations - filter: {{ Dimension('company__tier' )}} = 'enterprise' # constraint only applies to the numerator + filter: {{ Dimension('company__tier' )}} = 'enterprise' denominator: transaction_amount - filter: | # add optional constraint string. This applies to both the numerator and denominator + filter: | {{ Dimension('customer__country') }} = 'MX' ``` From 9d398d4e42042c85fe27043648e09d0a5fdb197d Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 12:30:11 +0000 Subject: [PATCH 14/19] Update 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 42ba056a66c..791b5b213ea 100644 --- a/website/docs/docs/build/cumulative-metrics.md +++ b/website/docs/docs/build/cumulative-metrics.md @@ -248,7 +248,7 @@ limit 100; ``` ## Limitations -If you specify a `window` in your cumulatve metric definition, you must include `metric_time` as a dimension in the SQL query. This is because the accumulation window is based on metric time. For example, +If you specify a `window` in your cumulative metric definition, you must include `metric_time` as a dimension in the SQL query. This is because the accumulation window is based on metric time. For example, ```sql select From e1fd6070d4636708322bdc43a8a61f7368a29724 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 12:31:25 +0000 Subject: [PATCH 15/19] Update metrics-overview.md --- website/docs/docs/build/metrics-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index ce30da8ca89..fb8487f0eef 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -45,7 +45,7 @@ import SLCourses from '/snippets/_sl-course.md'; ### Conversion metrics -[Conversion metrics](/docs/build/conversion) help you track when a base event and a subsequent conversion event occurs for an entity within a set time period. +[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. ```yaml metrics: From 6c82606f735f5f1493a36ad13421310f26006476 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 12:31:53 +0000 Subject: [PATCH 16/19] Update ratio-metrics.md --- website/docs/docs/build/ratio-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/ratio-metrics.md b/website/docs/docs/build/ratio-metrics.md index ba97ca899ea..18abe090d42 100644 --- a/website/docs/docs/build/ratio-metrics.md +++ b/website/docs/docs/build/ratio-metrics.md @@ -56,7 +56,7 @@ metrics: ## Ratio metrics using different semantic models -The system will simplify and turn the numerator and denominator in a ratio metric from different semantic models by computing their values in sub-queries. It will then join the result set based on common dimensions to calculate the final ratio. Here's an example of the SQL generated for such a ratio metric. +The system will simplify and turn the numerator and denominator into a ratio metric from different semantic models by computing their values in sub-queries. It will then join the result set based on common dimensions to calculate the final ratio. Here's an example of the SQL generated for such a ratio metric. ```sql From 8018b2379cb5863d8285d67261b5bea5b4317156 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 12:32:31 +0000 Subject: [PATCH 17/19] Update semantic-models.md --- website/docs/docs/build/semantic-models.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/build/semantic-models.md b/website/docs/docs/build/semantic-models.md index 472d1bd1f18..efa0d66a894 100644 --- a/website/docs/docs/build/semantic-models.md +++ b/website/docs/docs/build/semantic-models.md @@ -53,9 +53,9 @@ semantic_models: entities: ## Required - see more information in entities measures: ## Optional - - see more information in measures section + - see more information in the measures section dimensions: ## Required - - see more information in dimensions section + - see more information in the dimensions section primary_entity: >- if the semantic model has no primary entity, then this property is required. #Optional if a primary entity exists, otherwise Required ``` @@ -223,7 +223,7 @@ You can refer to entities (join keys) in a semantic model using the `name` param [Dimensions](/docs/build/dimensions) are the different ways you can group or slice data for a metric. It can be time-consuming and error-prone to anticipate all possible options in a single table, such as region, country, user role, and so on. -MetricFlow simplifies this by allowing you to query all metric groups and construct the join during the query. To specify dimensions parameters, include the `name` (either a column or SQL expression) and `type` (`categorical` or `time`). Categorical groups represent qualitative values, while time groups represent dates of varying granularity. +MetricFlow simplifies this by allowing you to query all metric groups and construct the join during the query. To specify dimension parameters, include the `name` (either a column or SQL expression) and `type` (`categorical` or `time`). Categorical groups represent qualitative values, while time groups represent dates of varying granularity. Dimensions are identified using the name parameter, just like identifiers. The naming of groups must be unique within a semantic model, but not across semantic models since MetricFlow, uses entities to determine the appropriate groups. MetricFlow requires all dimensions be tied to a primary entity. From 5edce49b5a5218d9dc0a0a6eb0e45de0ae7f7a93 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 12:32:58 +0000 Subject: [PATCH 18/19] Update semantic-models.md --- website/docs/docs/build/semantic-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/semantic-models.md b/website/docs/docs/build/semantic-models.md index efa0d66a894..1cc7bcdfe63 100644 --- a/website/docs/docs/build/semantic-models.md +++ b/website/docs/docs/build/semantic-models.md @@ -225,7 +225,7 @@ You can refer to entities (join keys) in a semantic model using the `name` param MetricFlow simplifies this by allowing you to query all metric groups and construct the join during the query. To specify dimension parameters, include the `name` (either a column or SQL expression) and `type` (`categorical` or `time`). Categorical groups represent qualitative values, while time groups represent dates of varying granularity. -Dimensions are identified using the name parameter, just like identifiers. The naming of groups must be unique within a semantic model, but not across semantic models since MetricFlow, uses entities to determine the appropriate groups. MetricFlow requires all dimensions be tied to a primary entity. +Dimensions are identified using the name parameter, just like identifiers. The naming of groups must be unique within a semantic model, but not across semantic models since MetricFlow, uses entities to determine the appropriate groups. MetricFlow requires all dimensions to be tied to a primary entity. :::info For time groups From a942f8b03767c33eb562b58390fa855c4293ea73 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 21 Feb 2024 17:02:13 +0000 Subject: [PATCH 19/19] Update conversion-metrics.md --- website/docs/docs/build/conversion-metrics.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/website/docs/docs/build/conversion-metrics.md b/website/docs/docs/build/conversion-metrics.md index 9e832060df9..70045b1acf2 100644 --- a/website/docs/docs/build/conversion-metrics.md +++ b/website/docs/docs/build/conversion-metrics.md @@ -104,7 +104,7 @@ Next, define a conversion metric as follows: label: Visit to Buy Conversion Rate (7-day window) type_params: conversion_type_params: - base_measure: visits + base_measure: name: visits fill_nulls_with: 0 conversion_measure: sellers @@ -272,7 +272,8 @@ To return zero in the final data set, you can set the value of a null conversion type_params: conversion_type_params: calculation: conversions - base_measure: visits + base_measure: + name: visits conversion_measure: name: buys fill_nulls_with: 0 @@ -301,7 +302,8 @@ You can change the default to display the number of conversions by setting the ` type_params: conversion_type_params: calculation: conversions - base_measure: visits + base_measure: + name: visits conversion_measure: name: buys fill_nulls_with: 0 @@ -333,7 +335,8 @@ In this case, you want to set `product_id` as the constant property. You can spe type_params: conversion_type_params: calculation: conversions - base_measure: view_item_detail + base_measure: + name: view_item_detail conversion_measure: purchase entity: user window: 1 week