add conversion-metrics-docs

website/docs/docs/build/conversion-metrics.md

@@ -0,0 +1,326 @@
+---
+title: "Conversion metrics"
+id: conversion
+description: "Use Conversion metrics to measure conversion events."
+sidebar_label: Conversion
+tags: [Metrics, Semantic Layer]
+---
+
+Conversion metrics allow us to define when a base event happens and a subsequent conversion event happens for a specific entity within some time range.
+
+- **Example**: Track how often a user (entity) completes a visit (base event) and then makes a purchase (conversion event) within 7 days (time window).
+- **Requirements**: A time range and an entity to join on.
+- **How it differs from [Ratio metrics](/docs/build/ratio)**: Includes an entity in the pre-aggregated join.
+
+## Parameters
+
+The specification for conversion metrics is as follows:
+
+| Parameter | Description | Type | Required/Optional |
+| --- | --- | --- | --- |
+| name | The name of the metric. | String | Required |
+| description | The description of the metric. | String | Optional |
+| type | The type of the 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_parameters | Specific configurations for each metric type. | List | Required |
+| 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`. Default is `conversion_rate`. | String | Required |
+| base_measure | The base conversion event measure. | Measure | Required |
+| conversion_measure | The conversion event measure. | Measure | Required |
+| window | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity.  | String | Required |
+| constant_properties | List of constant properties. Defaults to None.  | 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 |
+
+The following code example displays the complete specification for conversion metrics and details how they're applied:
+
+```yaml
+metrics:
+  - name: The metric name # Required
+    description: the metric description # Required
+    type: conversion
+    type_params:
+      conversion_type_params:
+        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
+        window: _time_window_ # Optional. default: inf. window to join the two events on. Follows 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
+```
+
+## Conversion metric example
+
+The following example will measure conversions from website visits (`VISITS` table) to order completions (`BUYS` table). Let's calculate a conversion metric step by step.
+
+Suppose we have two semantic models, `VISITS` and `BUYS`:
+
+- The `VISITS` table represents visits to an e-commerce site
+- The `BUYS` table represents someone completing an order on that site.  
+
+The underlying tables look like the following:
+
+`VISITS`<br />
+Contains user visits with `USER_ID` and `REFERRER_ID`.
+
+| DS | USER_ID | REFERRER_ID |
+| --- | --- | --- |
+| 2020-01-01 | bob | facebook |
+| 2020-01-04 | bob | google |
+| 2020-01-07 | bob | amazon |
+
+`BUYS`<br />
+Records completed orders with `USER_ID` and `REFERRER_ID`.
+
+| DS | USER_ID | REFERRER_ID |
+| --- | --- | --- |
+| 2020-01-02 | bob | facebook |
+| 2020-01-07 | bob | amazon |
+
+Next, we define a conversion metric as follows:
+
+```yaml
+- name: visit_to_buy_conversion_rate_7d
+  description: "Conversion rate from visiting to transaction in 7 days"
+  type: conversion
+  label: Visit to Buy Conversion Rate (7 day window)
+  type_params:
+    conversion_type_params:
+      base_measure: visits
+      conversion_measure: sellers
+      entity: user
+      window: 7 days
+```
+
+To calculate the conversion, link the `BUYS` event to the nearest `VISITS` event (or closest base event). The following steps explain this process in more detail:
+
+### Step 1: Join `VISITS` and `BUYS`
+
+This step joins the `BUYS` table to the `VISITS` table and gets all combinations of visits-buys events that match the join condition where buys occur within 7 days of the visit (any rows that have the same user and a buy happened at most 7 days after the visit).
+
+The SQL generated in these steps looks like the following:
+
+```sql
+select
+  v.ds,
+  v.user_id,
+  v.referrer_id,
+  b.ds,
+  b.uuid,
+  1 as buys
+from visits v
+inner join (
+    select *, uuid_string() as uuid from buys -- Adds a uuid column to uniquely identify the different rows
+) b
+on
+v.user_id = b.user_id and v.ds <= b.ds and v.ds > b.ds - interval '7 day'
+```
+
+The dataset returns the following:
+Note that there are two potential conversion events for the first visit.
+
+| V.DS | V.USER_ID | V.REFERRER_ID | B.DS | UUID | BUYS |
+| --- | --- | --- | --- | --- | --- |
+| 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 |
+| 2020-01-01 | bob | facebook | 2020-01-07 | uuid2 | 1 |
+| 2020-01-04 | bob | google | 2020-01-07 | uuid2 | 1 |
+| 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 |
+
+### Step 2: Refine with Window Function
+
+Instead of returning the raw visit values, use window functions to link conversions to the closest base event. You can partition by the conversion source and get the `first_value` ordered by `visit ds`, descending to get the closest base event from the conversion event:
+
+```sql
+select
+  first_value(v.ds) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc nulls first) as v_ds,
+  first_value(v.user_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc nulls first) as user_id,
+  first_value(v.referrer_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc nulls first) as referrer_id,
+  b.ds,
+  b.uuid,
+  1 as buys
+from visits v
+inner join (
+    select *, uuid_string() as uuid from buys
+) b
+on
+v.user_id = b.user_id and v.ds <= b.ds and v.ds > b.ds - interval '7 day'
+
+```
+
+The dataset returns the following:
+
+| V.DS | V.USER_ID | V.REFERRER_ID | B.DS | UUID | BUYS |
+| --- | --- | --- | --- | --- | --- |
+| 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 |
+| 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 |
+| 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 |
+| 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 |
+
+This workflow links the two conversions to the correct visit events. Due to the join, we end up with multiple combinations, leading to fanout results. After applying the window function, duplicates appear. 
+
+To resolve this and eliminate duplicates, use a distinct select, and the UUID helps identify which conversion is unique.
+
+### Step 3: Remove duplicates
+
+Instead of regular select in the [Step 2](#step-2-refine-with-window-function), use a distinct select to remove the duplicates.
+
+```sql
+SELECT DISTINCT
+  first_value(v.ds) OVER (PARTITION BY b.ds, b.user_id, b.uuid ORDER BY v.ds DESC NULLS FIRST) AS v.ds
+  , first_value(v.user_id) OVER (PARTITION BY b.ds, b.user_id, b.uuid ORDER BY v.ds DESC NULLS FIRST) AS user_id
+  , first_value(v.referrer_id) OVER (PARTITION BY b.ds, b.user_id, b.uuid ORDER BY v.ds DESC NULLS FIRST) AS referrer_id
+  , b.ds
+  , b.uuid
+  , 1 AS buys
+FROM VISITS v
+INNER JOIN (
+    SELECT *, UUID_STRING() AS uuid FROM BUYS
+) b
+ON
+v.user_id = b.user_id AND v.ds <= b.ds AND v.ds > b.ds - INTERVAL '7 day';
+```
+
+| V.DS | V.USER_ID | V.REFERRER_ID | B.DS | UUID | BUYS |
+| --- | --- | --- | --- | --- | --- |
+| 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 |
+| 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 |
+
+Now we have a data set that contains each conversion linked to a visit event.
+
+1. aggregate the "conversions" table to get the total number of conversions
+2. join the aggregated base measure table "opportunities" to the "conversions" table using the group by keys
+3. calculate the conversion
+
+### **Step 4:**
+
+Now that we’ve tied each conversion event to a visit we can calculate the aggregated conversions and opportunities measures, and join them to calculate the actual conversion rate. The SQL to calculate the conversion rate is as follows: 
+
+```sql
+SELECT
+  COALESCE(subq_3.metric_time__day, subq_13.metric_time__day) AS metric_time__day
+, CAST(MAX(subq_13.buys) AS DOUBLE) / CAST(NULLIF(MAX(subq_3.visits), 0) AS DOUBLE) AS visit_to_buy_conversion_rate_7d
+FROM ( -- Base Measure
+  SELECT
+    metric_time__day
+    , SUM(visits) AS mqls
+  FROM (
+    SELECT
+      DATE_TRUNC('day', first_contact_date) AS metric_time__day
+      , 1 as visits
+    FROM visits
+  ) subq_2
+  GROUP BY
+    metric_time__day
+) subq_3
+FULL OUTER JOIN ( -- Conversion Measure
+  SELECT
+    metric_time__day
+    , SUM(buys) AS sellers
+  FROM (
+	.....
+#The output of this subquery is the table produced in Step 3. The SQL is hidden for legibility. 
+#To see the full SQL output and --explain to your conversion metric query. 
+  ) subq_10
+  GROUP BY
+    metric_time__day
+) subq_13
+ON
+  subq_3.metric_time__day = subq_13.metric_time__day
+GROUP BY
+```
+
+**Set the value of null conversion events**
+
+You may want to set the value of a null conversion event to zero instead of null, so the final data set returns zero. You can add the `fill_nulls_with` parameter to your conversion metric definition like this:
+
+```yaml
+- name: vist_to_buy_conversion_rate_7_day_window
+    description: "Conversion rate from MQL to seller"
+    type: conversion
+    label: MQL to Seller Conversion Rate (1 week day window)
+    type_params:
+      conversion_type_params:
+        # calculation: CONVERSIONS
+        base_measure: mqls
+        conversion_measure: 
+          name: sellers
+          fill_nulls_with: 0
+        entity: mql
+        window: 1 week
+```
+
+This will return the following result set:
+
+<Lightbox src="/img/docs/dbt-cloud/semantic-layer/conversion-metrics-fill-null.png" width="85%" title="Conversion metric with fill nulls with parameter"/>
+
+**Setting the calculation type:**
+
+The conversion calculation parameter can be used to either show the raw number of conversions or the conversion rate. The default value is the conversion rate. I can change the default to show the number of conversions by setting the `calculation: conversion` parameter:
+
+```yaml
+- name: vist_to_buy_conversions_1_week_window
+    description: "Visit to Buy Conversions"
+    type: conversion
+    label: Visit to Buy Conversions (1 week window)
+    type_params:
+      conversion_type_params:
+        calculation: conversions
+        base_measure: visits
+        conversion_measure: 
+          name: buys
+          fill_nulls_with: 0
+        entity: user
+        window: 1 week
+```
+
+**Setting a constant property for a conversion metric**
+
+*If you’re not sure what a constant property is [Amplitude has a great blog post on constant properties. I recommend](https://amplitude.com/blog/holding-constant) reading this to get up to speed on the concept.*
+
+It's possible to add a constant property to a conversion metric to only count a conversions if this dimension or entity is the same for both the base and conversion event. For example, say you work at an e-commerce company and want to answer the following questions:
+
+*How often did visitors convert from View Item Details to Complete Purchase with the same product in each step?*
+
+What makes this question tricky to answer is users could have completed these two conversion milestones across many products. For example, viewed a pair of shoes, then a T-shirt,  and eventually checked out with a bow tie. This would still count as a conversion, even tho the conversion event only happened for the bow tie. 
+
+Back to our initial questions, we want to see how many customers viewed an item detail page and then completed *a purchase for the same product.* In this case, we would want to set product_id as the constant property. We would specify this in the configs as follows:
+
+```yaml
+- name: view_item_detail_to_purchase_with_same_item
+    description: "Conversion rate for users who viewed the item detail page and purchased the item"
+    type: Conversion
+    label: View Item Detail > Purchase 
+    type_params:
+      conversion_type_params:
+        calculation: conversions
+        base_measure: view_item_detail
+        conversion_measure: purchase
+        entity: user
+        window: 1 week
+				constant_properties:
+        - base_property: product
+          conversion_property: product
+```
+
+We will add an additional condition to the join to make sure the constant property is the same across conversion. 
+
+```sql
+SELECT DISTINCT
+        first_value(v.ds) OVER (PARTITION BY buy_source.ds, buy_source.user_id, buy_source.session_id ORDER BY v.ds DESC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS ds
+        , first_value(v.user_id) OVER (PARTITION BY buy_source.ds, buy_source.user_id, buy_source.session_id ORDER BY v.ds DESC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS user_id
+        , first_value(v.referrer_id) OVER (PARTITION BY buy_source.ds, buy_source.user_id, buy_source.session_id ORDER BY v.ds DESC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS referrer_id
+        , buy_source.uuid
+        , 1 AS buys
+        FROM {{ source_schema }}.fct_view_item_details v
+        INNER JOIN
+        (
+          SELECT *, {{ generate_random_uuid() }} AS uuid FROM {{ source_schema }}.fct_purchases
+        ) buy_source
+        ON
+         v.user_id = buy_source.user_id
+         v.user_id = b.user_id AND v.ds <= b.ds AND v.ds > b.ds - INTERVAL '7 day';
+         AND buy_source.product_id = v.product_id #Joining on the constant property product ID
+```

website/sidebars.js

@@ -323,6 +323,7 @@ const sidebarSettings = {
               link: { type: "doc", id: "docs/build/metrics-overview" },
               items: [
                 "docs/build/metrics-overview",
+                "docs/build/conversion",
                 "docs/build/cumulative",
                 "docs/build/derived",
                 "docs/build/ratio",