feature/country-region-reports

.buildkite/scripts/run_models.sh

@@ -19,7 +19,6 @@ dbt deps
 dbt seed --target "$db" --full-refresh
 dbt run --target "$db" --full-refresh
 dbt test --target "$db"
-## UPDATE FOR VARS HERE, IF NO VARS, PLEASE REMOVE
-dbt run --vars '{linkedin_ads__use_local_currency: true, ad_reporting__url_report__using_null_filter: false}' --target "$db" --full-refresh
-dbt test --vars '{linkedin_ads__use_local_currency: true, ad_reporting__url_report__using_null_filter: false}' --target "$db"
+dbt run --vars '{linkedin_ads__use_local_currency: true, ad_reporting__url_report__using_null_filter: false, linkedin_ads__using_geo: False, linkedin_ads__using_monthly_ad_analytics_by_member_country: False, linkedin_ads__using_monthly_ad_analytics_by_member_region: False}' --target "$db" --full-refresh
+dbt test --vars '{linkedin_ads__use_local_currency: true, ad_reporting__url_report__using_null_filter: false, linkedin_ads__using_geo: False, linkedin_ads__using_monthly_ad_analytics_by_member_country: False, linkedin_ads__using_monthly_ad_analytics_by_member_region: False}' --target "$db"
 dbt run-operation fivetran_utils.drop_schemas_automation --target "$db"

.quickstart/quickstart.yml

@@ -3,6 +3,14 @@ schema_key: linkedin_ads_schema
 
 dbt_versions: ">=1.3.0 <2.0.0"
 
+table_variables:
+  linkedin_ads__using_geo:
+    - geo
+  linkedin_ads__using_monthly_ad_analytics_by_member_country:
+    - monthly_ad_analytics_by_member_country
+  linkedin_ads__using_monthly_ad_analytics_by_member_region:
+    - monthly_ad_analytics_by_member_region
+
 destination_configurations:
   databricks:
     dispatch:
@@ -14,5 +22,7 @@ public_models: [
   "linkedin_ads__creative_report",
   "linkedin_ads__campaign_report",
   "linkedin_ads__account_report",
-  "linkedin_ads__url_report"
+  "linkedin_ads__url_report",
+  "linkedin_ads__monthly_campaign_country_report",
+  "linkedin_ads__monthly_campaign_region_report"
 ]

CHANGELOG.md

@@ -1,9 +1,32 @@
-# dbt_linkedin version.version
+# dbt_linkedin v0.11.0
+
+[PR #44](https://github.com/fivetran/dbt_linkedin/pull/44) includes the following updates:
+
+## Schema Changes
+**8 total changes • 0 possible breaking changes**
+| Data Model                                    | Change Type | Old Name | New Name                                  | Notes                                                             |
+|---------------------------------------------------|-------------|----------|-------------------------------------------|-------------------------------------------------------------------|
+| [linkedin_ads__monthly_campaign_country_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__monthly_campaign_country_report)       | New transformation model   |          |  | Table that represents the monthly performance of a campaign at the country level.               |
+| [linkedin_ads__monthly_campaign_region_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__monthly_campaign_region_report)       | New transformation model   |          |  | Table that represents the monthly performance of a campaign at the region level.              |
+| [stg_linkedin_ads__geo_tmp](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__geo_tmp)       | New temp model   |          |  | Temp model added for `geo`.               |
+| [stg_linkedin_ads__geo](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__geo)          | New staging model   |          |    | Staging model added for `geo`.         |
+| [stg_linkedin_ads__monthly_ad_analytics_by_country_tmp](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__monthly_ad_analytics_by_country_tmp)          | New temp model   |          |    | Temp model added for `monthly_ad_analytics_by_member_country`.         |
+| [stg_linkedin_ads__monthly_ad_analytics_by_country](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__monthly_ad_analytics_by_country)          | New staging model   |          |    | Staging model added for `monthly_ad_analytics_by_member_country`.         |
+| [stg_linkedin_ads__monthly_ad_analytics_by_region_tmp](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__monthly_ad_analytics_by_region_tmp)          | New temp model   |          |    | Temp model added for `monthly_ad_analytics_by_member_region`. Name shortened for warehouse table name length compatibility.         |
+| [stg_linkedin_ads__monthly_ad_analytics_by_region](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin_source.stg_linkedin_ads__monthly_ad_analytics_by_region)          | New staging model   |          |    | Staging model added for `monthly_ad_analytics_by_member_region`. Name shortened for warehouse table name length compatibility.           |
+
+## Feature Updates
+- Added the `geo`, `monthly_ad_analytics_by_member_country` and `monthly_ad_analytics_by_member_region` source tables and downstream staging models. See above for schema change details and new models added.
+  - For dbt Core users: If you do not sync these tables or would like disable these new models you can disable the models by setting the any of the `linkedin_ads__using_geo`, `linkedin_ads__using_monthly_ad_analytics_by_member_country`, or `linkedin_ads__using_monthly_ad_analytics_by_member_region` variables to `false` in your `dbt_project.yml` file (`true` by default). Refer to the [README](https://github.com/fivetran/dbt_linkedin/tree/main?tab=readme-ov-file#passing-through-additional-metrics) for more details.
+- Included the `linkedin_ads__monthly_ad_analytics_by_member_country_passthrough_metrics` and `linkedin_ads__monthly_ad_analytics_by_member_region_passthrough_metrics` passthrough variables in the above mentioned new staging models. Refer to the [README](https://github.com/fivetran/dbt_linkedin/tree/main?tab=readme-ov-file#passing-through-additional-metrics) for more details.
 
 ## Documentation
 - Added Quickstart model counts to README. ([#43](https://github.com/fivetran/dbt_linkedin/pull/43))
 - Corrected references to connectors and connections in the README. ([#43](https://github.com/fivetran/dbt_linkedin/pull/43))
 
+## Under the Hood
+- Added vertical integrity tests to ensure data accuracy of the new `linkedin_ads__monthly_campaign_country_report` and `linkedin_ads__monthly_campaign_region_report` models. ([#44](https://github.com/fivetran/dbt_linkedin/pull/44))
+
 # dbt_linkedin v0.10.0
 [PR #38](https://github.com/fivetran/dbt_linkedin/pull/38) includes the following updates:
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright © 2025 Fivetran Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,4 +1,6 @@
-<p align="center">
+# LinkedIn Ad Analytics Transformation dbt Package ([docs](https://fivetran.github.io/dbt_linkedin/))
+
+<p align="left">
     <a alt="License"
         href="https://github.com/fivetran/dbt_linkedin/blob/main/LICENSE">
         <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" /></a>
@@ -13,7 +15,6 @@
         <img src="https://img.shields.io/badge/Fivetran_Quickstart_Compatible%3F-yes-green.svg" /></a>
 </p>
 
-# LinkedIn Ad Analytics Transformation dbt Package ([docs](https://fivetran.github.io/dbt_linkedin/))
 ## What does this dbt package do?
 - Produces modeled tables that leverage Linkedin Ad Analytics data from [Fivetran's connector](https://fivetran.com/docs/applications/linkedin-ads) in the format described by [this ERD](https://fivetran.com/docs/applications/linkedin-ads#schemainformation) and builds off the output of our [Linkedin Ads source package](https://github.com/fivetran/dbt_linkedin_source).
 - Enables you to better understand the performance of your ads across varying grains:
@@ -27,14 +28,16 @@ The following table provides a detailed list of all tables materialized within t
 
 | **Table**                          | **Description**                                                                                                        |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| [linkedin_ads__account_report](https://github.com/fivetran/dbt_linkedin/blob/main/models/linkedin_ads__account_report.sql)        | Each record represents the daily ad performance of each account.                                                       |
-| [linkedin_ads__campaign_report](https://github.com/fivetran/dbt_linkedin/blob/main/models/linkedin_ads__campaign_report.sql)       | Each record represents the daily ad performance of each campaign. Linkedin campaigns map onto ad groups in other ad platforms.                                                      |
-| [linkedin_ads__campaign_group_report](https://github.com/fivetran/dbt_linkedin/blob/main/models/linkedin_ads__campaign_group_report.sql) | Each record represents the daily ad performance of each campaign group. Linkedin                                                 |
-| [linkedin_ads__creative_report](https://github.com/fivetran/dbt_linkedin/blob/main/models/linkedin_ads__creative_report.sql) | Each record represents the daily ad performance of each creative.                                                |
-| [linkedin_ads__url_report](https://github.com/fivetran/dbt_linkedin/blob/main/models/linkedin_ads__url_report.sql) | Each record represents the daily ad performance of each url.                                                |
+| [linkedin_ads__account_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__account_report)        | Each record represents the daily ad performance of each account.                                                       |
+| [linkedin_ads__campaign_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__campaign_report)       | Each record represents the daily ad performance of each campaign. Linkedin campaigns map onto ad groups in other ad platforms.                                                      |
+| [linkedin_ads__monthly_campaign_country_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__monthly_campaign_country_report)       | Each record represents the monthly performance of a campaign at the country level.                                                      |
+| [linkedin_ads__monthly_campaign_region_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__monthly_campaign_region_report)       | Each record represents the monthly performance of a campaign at the region level.                                                      |
+| [linkedin_ads__campaign_group_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__campaign_group_report) | Each record represents the daily ad performance of each campaign group. Linkedin                                                 |
+| [linkedin_ads__creative_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__creative_report) | Each record represents the daily ad performance of each creative.                                                |
+| [linkedin_ads__url_report](https://fivetran.github.io/dbt_linkedin/#!/model/model.linkedin.linkedin_ads__url_report) | Each record represents the daily ad performance of each url.                                                |
 
 ### Materialized Models
-Each Quickstart transformation job run materializes 17 models if all components of this data model are enabled. This count includes all staging, intermediate, and final models materialized as `view`, `table`, or `incremental`.
+Each Quickstart transformation job run materializes 25 models if all components of this data model are enabled. This count includes all staging, intermediate, and final models materialized as `view`, `table`, or `incremental`.
 <!--section-end-->
 
 ## How do I use the dbt package?
@@ -58,7 +61,7 @@ Include the following Linkedin Ads package version in your `packages.yml` file:
 # packages.yml
 packages:
   - package: fivetran/linkedin
-    version: [">=0.10.0", "<0.11.0"]
+    version: [">=0.11.0", "<0.12.0"]
 ```
 Do **NOT** include the `linkedin_source` package in this file. The transformation package itself has a dependency on it and will install the source package as well.
 
@@ -85,6 +88,15 @@ vars:
 
 To connect your multiple schema/database sources to the package models, follow the steps outlined in the [Union Data Defined Sources Configuration](https://github.com/fivetran/dbt_fivetran_utils/tree/releases/v0.4.latest#union_data-source) section of the Fivetran Utils documentation for the union_data macro. This will ensure a proper configuration and correct visualization of connections in the DAG.
 
+#### Disable Country and Region Reports
+This package leverages the `geo`, `monthly_ad_analytics_by_member_country`, and `monthly_ad_analytics_by_member_region` tables to help report on campaign performance by country and region. However, if you are not actively syncing these reports from your LinkedIn Ads connection, you may disable relevant transformations by adding the following variable configuration to your root `dbt_project.yml` file:
+```yml
+vars:
+    linkedin_ads__using_geo: False # True by default
+    linkedin_ads__using_monthly_ad_analytics_by_member_country: False # True by default
+    linkedin_ads__using_monthly_ad_analytics_by_member_region: False # True by default
+```
+
 #### Switching to Local Currency
 Additionally, the package allows you to select whether you want to add in costs in USD or the local currency of the ad. By default, the package uses USD. If you would like to have costs in the local currency, add the following variable to your `dbt_project.yml` file:
 
@@ -97,7 +109,7 @@ vars:
 **Note**: Unlike cost, conversion values are only available in the local currency. The package will only use the `conversion_value_in_local_currency` field for conversion values, while it may draw from the `cost_in_local_currency` and `cost_in_usd` source fields for cost.
 
 #### Passing Through Additional Metrics
-By default, this package will select `clicks`, `impressions`, `cost`, `conversion_value_in_local_currency`, and `total_conversions` (as well as fields set via `linkedin_ads__conversion_fields` in the next section) from the source reporting tables to store into the staging models. If you would like to pass through additional metrics to the staging models, add the below configurations to your `dbt_project.yml` file. These variables allow for the pass-through fields to be aliased (`alias`) if desired, but not required. Use the below format for declaring the respective pass-through variables:
+By default, this package will select `clicks`, `impressions`, `cost` and `conversion_value_in_local_currency` (as well as fields set via `linkedin_ads__conversion_fields` in the next section) from the source reporting tables `ad_analytics_by_campaign`, `ad_analytics_by_creative`, `monthly_ad_analytics_by_member_country`, and `monthly_ad_analytics_by_member_region` to store into the corresponding staging models. If you would like to pass through additional metrics to the staging models, add the below configurations to your `dbt_project.yml` file. These variables allow for the pass-through fields to be aliased (`alias`) and transformed (`transform_sql`) if desired, but not required. Only the `name` of each metric field is required. Use the below format for declaring the respective pass-through variables:
 
 ```yml
 # dbt_project.yml
@@ -115,12 +127,19 @@ vars:
         - name: "new_custom_field"
           alias: "custom_field"
         - name: "unique_int_field"
+    linkedin_ads__monthly_ad_analytics_by_member_country_passthrough_metrics: # pulls from monthly_ad_analytics_by_member_country
+        - name: "country_custom_field"
+          alias: "country_field"
+    linkedin_ads__monthly_ad_analytics_by_member_region_passthrough_metrics: # pulls from monthly_ad_analytics_by_member_region
+        - name: "region_custom_field"
+          alias: "region_field"
+        - name: "region_field_two"
 ```
 
 >**Note** Please ensure you exercised due diligence when adding metrics to these models. The metrics added by default (clicks, impressions, and spend) have been vetted by the Fivetran team maintaining this package for accuracy. There are metrics included within the source reports, for example metric averages, which may be inaccurately represented at the grain for reports created in this package. You will want to ensure whichever metrics you pass through are indeed appropriate to aggregate at the respective reporting levels provided in this package. (**Important**: You do not need to add conversions in this way. See the following section for an alternative implementation.)
 
 #### Adding in Conversion Fields Variable
-Separate from the above passthrough metrics, the package will also include conversion metrics based on the `linkedin_ads__conversion_fields` variable, in addition to the `conversion_value_in_local_currency` field.
+Separate from the above passthrough metrics, the package will also include conversion metrics based on the `linkedin_ads__conversion_fields` variable, in addition to the `conversion_value_in_local_currency` field within the `ad_analytics_by_campaign`, `ad_analytics_by_creative`, `monthly_ad_analytics_by_member_country` and `monthly_ad_analytics_by_member_region` data models.
 
 By default, the data models consider `external_website_conversions` and `one_click_leads` to be conversions. These should cover most use cases, but if you wanted to adjust this to your business case, you would apply the following configuration with the **original** source names of the conversion fields (not aliases you provided in the section above):
 
@@ -170,7 +189,7 @@ This dbt package is dependent on the following dbt packages. These dependencies
 ```yml
 packages:
     - package: fivetran/linkedin_source
-      version: [">=0.10.0", "<0.11.0"]
+      version: [">=0.11.0", "<0.12.0"]
     - package: fivetran/fivetran_utils
       version: [">=0.4.0", "<0.5.0"]
     - package: dbt-labs/dbt_utils

dbt_project.yml

@@ -1,5 +1,5 @@
 name: 'linkedin'
-version: '0.10.0'
+version: '0.11.0'
 config-version: 2
 require-dbt-version: [">=1.3.0", "<2.0.0"]
 vars:
@@ -10,8 +10,13 @@ vars:
     campaign_group_history: "{{ ref('stg_linkedin_ads__campaign_group_history') }}"
     account_history: "{{ ref('stg_linkedin_ads__account_history') }}"
     ad_analytics_by_campaign: "{{ ref('stg_linkedin_ads__ad_analytics_by_campaign') }}"
+    geo: "{{ ref('stg_linkedin_ads__geo') }}"
+    monthly_ad_analytics_by_member_country: "{{ ref('stg_linkedin_ads__monthly_ad_analytics_by_country') }}"
+    monthly_ad_analytics_by_member_region: "{{ ref('stg_linkedin_ads__monthly_ad_analytics_by_region') }}"
   linkedin_ads__creative_passthrough_metrics: []
   linkedin_ads__campaign_passthrough_metrics: []
+  linkedin_ads__monthly_ad_analytics_by_member_country_passthrough_metrics: []
+  linkedin_ads__monthly_ad_analytics_by_member_region_passthrough_metrics: []
   linkedin_ads__conversion_fields: ['external_website_conversions', 'one_click_leads']
 
 models: