Merge pull request #61 from fivetran/release/v1.0.1

fivetran-jamie · web-flow · commit 2146d06da804 · 2022-09-27T15:50:35.000-07:00
release/v1.0.1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,20 @@
+# dbt_ad_reporting v1.0.1
+
+## 🎉 Feature Enhancements 🎉 
+[PR #57](https://github.com/fivetran/dbt_ad_reporting/pull/57) incorporates the following change:
+- The package now includes a set of pre-defined [metrics](https://docs.getdbt.com/docs/building-a-dbt-project/metrics) related to clicks, impressions, and spend (definitions [here](https://github.com/fivetran/dbt_ad_reporting/blob/main/models/ad_reporting_metrics.yml)). 
+  - Refer to the [README](https://github.com/fivetran/dbt_ad_reporting#optional-step-8-use-predefined-metrics) for the included metrics and instructions on how to use them.
+  - Note: This requires you to manually add a dependency on the [dbt metrics package](https://github.com/dbt-labs/dbt_metrics) to use.
+
+## Fixes
+[PR #60](https://github.com/fivetran/dbt_ad_reporting/pull/60) incorporates the following change:
+- The LinkedIn Ads schema and database variables were incorrectly documented within the README. The README has been updated to reflect the correct variable names. 
+  - `linkedin_schema` has been properly updated to reflect `linkedin_ads_schema`
+  - `linkedin_database` has been updated to reflect `linkedin_ads_database`. 
+
+## Contributors
+- [@clay-walker](https://github.com/clay-walker) ([#60](https://github.com/fivetran/dbt_ad_reporting/pull/60))
+
 # dbt_ad_reporting v1.0.0
 ## 🚨 Breaking Changes 🚨
 [PR #54](https://github.com/fivetran/dbt_ad_reporting/pull/54) incorporates these breaking changes:
diff --git a/README.md b/README.md
@@ -81,8 +81,8 @@ vars:
     microsoft_ads_schema: bingads
     microsoft_ads_database: your_database_name
 
-    linkedin_schema: linkedin_ads 
-    linkedin_database: your_database_name  
+    linkedin_ads_schema: linkedin_ads 
+    linkedin_ads_database: your_database_name  
 
     pinterest_schema: pinterest
     pinterest_database: your_database_name 
@@ -209,6 +209,50 @@ Fivetran offers the ability for you to orchestrate your dbt project through [Fiv
 </details>
 <br>
 
+## (Optional) Step 8: Use predefined Metrics
+<details><summary>Expand for details</summary>
+
+On top of the `ad_reporting__ad_report` final model, the Ad Reporting dbt package defines common [Metrics](https://docs.getdbt.com/docs/building-a-dbt-project/metrics), including:
+- Spend
+- Impressions
+- Clicks
+- Cost per click
+- Clickthrough rate
+- Bounce rate
+- Count of active ads
+- Average spend
+- Average non-zero spend
+
+You can find the supported dimensions and full definitions of these metrics [here](https://github.com/fivetran/dbt_ad_reporting/blob/main/models/ad_reporting_metrics.yml).
+
+To use dbt Metrics, add the [dbt metrics package](https://github.com/dbt-labs/dbt_metrics) to your project's `packages.yml` file:
+```yml
+packages:
+  - package: dbt-labs/metrics
+    version: [">=0.3.0", "<0.4.0"]
+```
+> **Note**: The Metrics package has stricter dbt version requirements. As of today, the latest version of Metrics (v0.3.5) requires dbt `[">=1.2.0-a1", "<2.0.0"]`.
+
+To utilize the Ad Reporting's pre-defined metrics in your code, refer to the [dbt metrics package](https://github.com/dbt-labs/dbt_metrics) usage instructions and the example below:
+```sql
+select *
+from {{ metrics.calculate(
+        metric('clicks'),
+        grain='month',
+        dimensions=['platform', 
+                    'campaign_id', 
+                    'campaign_name'
+        ],
+        secondary_calculations=[
+            metrics.period_over_period(comparison_strategy='difference', interval=1, alias='diff_last_mth'),
+            metrics.period_over_period(comparison_strategy='ratio', interval=1, alias='ratio_last_mth')
+        ]
+) }}
+```
+
+</details>
+<br>
+
 # 🔍 Does this package have dependencies?
 This dbt package is dependent on the following dbt packages. For more information on the below packages, refer to the [dbt hub](https://hub.getdbt.com/) site.
 > **If you have any of these dependent packages in your own `packages.yml` I highly recommend you remove them to ensure there are no package version conflicts.**
diff --git a/dbt_project.yml b/dbt_project.yml
@@ -1,5 +1,5 @@
 name: 'ad_reporting'
-version: '1.0.0'
+version: '1.0.1'
 config-version: 2
 
 require-dbt-version: [">=1.0.0", "<2.0.0"]
diff --git a/integration_tests/dbt_project.yml b/integration_tests/dbt_project.yml
@@ -1,5 +1,5 @@
 name: 'ad_reporting_integration_tests'
-version: '1.0.0'
+version: '1.0.1'
 profile: 'integration_tests'
 config-version: 2
 
diff --git a/integration_tests/requirements.txt b/integration_tests/requirements.txt
@@ -1,6 +1,6 @@
-dbt-snowflake~=1.0.0
-dbt-bigquery~=1.0.0
-dbt-redshift~=1.0.0
-dbt-postgres~=1.0.0
-dbt-spark~=1.0.0
-dbt-spark[PyHive]~=1.0.0
+dbt-snowflake>=1.0.0
+dbt-bigquery>=1.0.0
+dbt-redshift>=1.0.0
+dbt-postgres>=1.0.0
+dbt-spark>=1.0.0
+dbt-spark[PyHive]>=1.0.0
diff --git a/models/ad_reporting_metrics.yml b/models/ad_reporting_metrics.yml
@@ -0,0 +1,201 @@
+version: 2
+
+metrics:
+  - name: spend
+    label: Ad spend (Fivetran)
+    model: ref('ad_reporting__ad_report')
+
+    type: sum
+    sql: spend
+    description: Total spend (in currency of individual platforms)
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: clicks
+    label: Ad clicks (Fivetran)
+    model: ref('ad_reporting__ad_report')
+
+    type: sum
+    sql: clicks
+    description: Total clicks
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: impressions
+    label: Ad impressions (Fivetran)
+    model: ref('ad_reporting__ad_report')
+    description: Total impressions
+
+    type: sum
+    sql: impressions
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: cost_per_click
+    label: Average ad cost per click (Fivetran)
+    description: The ratio of spend to clicks
+
+    type: expression
+    sql: "{{ metric('spend') }} / {{ metric('clicks') }}"
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: bounce_rate
+    label: Average Ad Bounce Rate (Fivetran)
+    description: Percentage of impressions that did not convert into clicks.
+
+    type: expression
+    sql: "({{ metric('impressions') }} - {{ metric('clicks') }}) / {{ metric('impressions') }}"
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: clickthrough_rate
+    label: Ad Clickthrough Rate (Fivetran)
+    description: Percentage of impressions that did convert into clicks.
+
+    type: expression
+    sql: "{{ metric('clicks') }} / {{ metric('impressions') }}"
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - ad_id
+      - ad_name
+      - account_id
+      - account_name
+
+  - name: active_ads
+    label: Count of Active Ads (Fivetran)
+    model: ref('ad_reporting__ad_report')
+    description: Count of ads witth spend > 0.
+
+    type: count_distinct
+    sql: ad_id
+
+    timestamp: date_day
+    time_grains: [day, week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - account_id
+      - account_name
+
+    filters:
+      - field: spend
+        operator: '>'
+        value: '0'
+
+  - name: avg_spend_nonzero
+    label: Average Spend, Ignore Zeros (Fivetran)
+    model: ref('ad_reporting__ad_report')
+    description: Average ad spend, ignores zero-spend days.
+
+    type: average
+    sql: spend
+
+    timestamp: date_day
+    time_grains: [week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - account_id
+      - account_name
+
+    filters:
+      - field: spend
+        operator: '>'
+        value: '0'
+
+  - name: avg_spend
+    label: Average Spend (Fivetran)
+    model: ref('ad_reporting__ad_report')
+    description: Average ad spend, does not ignore zero-spend days.
+
+    type: average
+    sql: spend
+
+    timestamp: date_day
+    time_grains: [week, month]
+
+    dimensions:
+      - platform
+      - campaign_id
+      - campaign_name
+      - ad_group_id
+      - ad_group_name
+      - account_id
+      - account_name
diff --git a/models/ad_reporting_models.yml b/models/ad_reporting_models.yml
