feature/country-region-reports

.buildkite/scripts/run_models.sh

@@ -19,8 +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}' --target "$db" --full-refresh
+dbt run --vars '{linkedin_ads__use_local_currency: True, 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 --target "$db"
-### END VARS CHUNK, REMOVE IF NOT USING
 dbt run-operation fivetran_utils.drop_schemas_automation --target "$db"

CHANGELOG.md

@@ -1,4 +1,25 @@
-# dbt_linkedin_source version.version
+# dbt_linkedin_source v0.11.0
+
+[PR #74](https://github.com/fivetran/dbt_linkedin_source/pull/74) includes the following updates:
+
+## Schema Changes
+**6 total changes • 0 possible breaking changes**
+| Data Model                                      | Change Type | Old Name | New Name                                  | Notes                                                             |
+|---------------------------------------------------|-------------|----------|-------------------------------------------|-------------------------------------------------------------------|
+| [stg_linkedin_ads__geo_tmp](https://fivetran.github.io/dbt_linkedin_source/#!/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_source/#!/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_source/#!/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_source/#!/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_source/#!/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_source/#!/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_source?tab=readme-ov-file#disable-country-and-region-reports) 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_source/tree/main?tab=readme-ov-file#passing-through-additional-metrics) for more details.
+
+## Under the Hood
+- Introduced the `date_from_month_string` macro to help convert the `date_month` field within the `stg_linkedin_ads__monthly_ad_analytics_by_region` and `stg_linkedin_ads__monthly_ad_analytics_by_county` models to be an appropriate date field as opposed to a string.
 
 ## Documentation
 - Corrected references to connectors and connections in the README. ([#73](https://github.com/fivetran/dbt_linkedin_source/pull/73))

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 Source dbt Package ([docs](https://fivetran.github.io/dbt_linkedin_source/))
+
+<p align="left">
     <a alt="License"
         href="https://github.com/fivetran/dbt_linkedin_source/blob/main/LICENSE">
         <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" /></a>
@@ -13,8 +15,6 @@
         <img src="https://img.shields.io/badge/Fivetran_Quickstart_Compatible%3F-yes-green.svg" /></a>
 </p>
 
-# LinkedIn Ad Analytics Source dbt Package ([docs](https://fivetran.github.io/dbt_linkedin_source/))
-
 ## What does this dbt package do?
 <!--section="linkedin_ads_source_model"-->
 - Materializes [Linkedin Ads Analytics staging tables](https://fivetran.github.io/dbt_linkedin_source/#!/overview/linkedin_source/models/?g_v=1&g_e=seeds) which leverage data in the format described by [this ERD](https://fivetran.com/docs/applications/linkedin-ads#schemainformation). These staging tables clean, test, and prepare your Linkedin Ads Analytics data from [Fivetran's connector](https://fivetran.com/docs/applications/linkedin-ads) for analysis by doing the following:
@@ -47,7 +47,7 @@ If you  are **not** using the [Linkedin transformation package](https://github.c
 # packages.yml
 packages:
   - package: fivetran/linkedin_source
-    version: [">=0.10.0", "<0.11.0"]
+    version: [">=0.11.0", "<0.12.0"]
 ```
 
 ### Step 3: Define database and schema variables
@@ -73,6 +73,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 for Costs
 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:
 
@@ -85,7 +94,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` 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` and `ad_analytics_by_creative` 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:
+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
@@ -103,12 +112,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, say, if you would like to consider landing page clicks and external post click conversions to *also* be conversions, you would apply the following configuration with the **original** source names of the conversion fields (not aliases you provided in the section above):
 

dbt_project.yml

@@ -1,5 +1,5 @@
 name: 'linkedin_source'
-version: '0.10.0'
+version: '0.11.0'
 config-version: 2
 require-dbt-version: [">=1.3.0", "<2.0.0"]
 models:
@@ -16,6 +16,11 @@ vars:
     campaign_history: "{{ source('linkedin_ads','campaign_history') }}"
     creative_history: "{{ source('linkedin_ads','creative_history') }}"
     ad_analytics_by_campaign: "{{ source('linkedin_ads', 'ad_analytics_by_campaign') }}"
+    geo: "{{ source('linkedin_ads', 'geo') }}"
+    monthly_ad_analytics_by_member_country: "{{ source('linkedin_ads', 'monthly_ad_analytics_by_member_country') }}"
+    monthly_ad_analytics_by_member_region: "{{ source('linkedin_ads', 'monthly_ad_analytics_by_member_region') }}"
   linkedin_ads__campaign_passthrough_metrics: []
   linkedin_ads__creative_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']

integration_tests/dbt_project.yml

@@ -1,5 +1,5 @@
 name: 'linkedin_source_integration_tests'
-version: '0.10.0'
+version: '0.11.0'
 profile: 'integration_tests'
 config-version: 2
 
@@ -11,12 +11,16 @@ vars:
     linkedin_ads_campaign_history_identifier: "linkedin_campaign_history_data"
     linkedin_ads_creative_history_identifier: "linkedin_creative_history_data"
     linkedin_ads_ad_analytics_by_campaign_identifier: "linkedin_ad_analytics_by_campaign_data"
+    linkedin_ads_geo_identifier: "linkedin_geo_data"
+    linkedin_ads_monthly_ad_analytics_by_member_country_identifier: "linkedin_monthly_ad_analytics_by_member_country_data"
+    linkedin_ads_monthly_ad_analytics_by_member_region_identifier: "linkedin_monthly_ad_analytics_by_member_region_data"
 
     linkedin_ads_schema: linkedin_source_integration_tests_3
-
     linkedin_ads__conversion_fields: ['external_website_conversions', 'one_click_leads']
 
 seeds:
+  +docs:
+    show: false
   linkedin_source_integration_tests:
     linkedin_creative_history_data:
       +column_types:
@@ -42,6 +46,14 @@ seeds:
       +column_types:
         created_time: timestamp
         last_modified_time: timestamp
+    linkedin_monthly_ad_analytics_by_member_country_data:
+      +column_types:
+        cost_in_local_currency: numeric
+        cost_in_usd: numeric
+    linkedin_monthly_ad_analytics_by_member_region_data:
+      +column_types:
+        cost_in_local_currency: numeric
+        cost_in_usd: numeric
 
 dispatch:
   - macro_namespace: dbt_utils

integration_tests/requirements.txt

@@ -4,4 +4,6 @@ dbt-redshift>=1.3.0,<2.0.0
 dbt-postgres>=1.3.0,<2.0.0
 dbt-spark>=1.3.0,<2.0.0
 dbt-spark[PyHive]>=1.3.0,<2.0.0
-dbt-databricks>=1.3.0,<2.0.0
+dbt-databricks>=1.3.0,<2.0.0
+
+certifi==2025.1.31