diff --git a/CHANGELOG.md b/CHANGELOG.md index bbfd434..0352145 100644 --- 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 index db80c12..a2505f8 100644 --- 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
+## (Optional) Step 8: Use predefined Metrics +
Expand for details + +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') + ] +) }} +``` + +
+
+ # 🔍 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 index abc505f..e3624fb 100644 --- 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 index aa90b52..d9d44e3 100644 --- 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 index 5c612de..4913903 100644 --- 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 \ No newline at end of file +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 \ No newline at end of file diff --git a/models/ad_reporting_metrics.yml b/models/ad_reporting_metrics.yml new file mode 100644 index 0000000..7b514eb --- /dev/null +++ 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 \ No newline at end of file diff --git a/models/ad_reporting.yml b/models/ad_reporting_models.yml similarity index 100% rename from models/ad_reporting.yml rename to models/ad_reporting_models.yml