Add geo reports

.buildkite/scripts/run_models.sh

@@ -19,4 +19,6 @@ dbt deps
 dbt seed --target "$db" --full-refresh
 dbt run --target "$db" --full-refresh
 dbt test --target "$db"
+dbt run --target "$db" --vars '{facebook_ads__using_demographics_country: true, facebook_ads__using_demographics_region: true}' --target "$db" --full-refresh
+dbt test --vars '{facebook_ads__using_demographics_country: true, facebook_ads__using_demographics_region: true}' --target "$db"
 dbt run-operation fivetran_utils.drop_schemas_automation --target "$db"

CHANGELOG.md

@@ -1,3 +1,31 @@
+# dbt_facebook_ads_source v0.9.0
+
+[PR #44](https://github.com/fivetran/dbt_facebook_ads_source/pull/44) introduces the following updates:
+
+## Schema Updates
+
+**9 total changes • 0 possible breaking changes**
+| **Data Model** | **Change type** | **Old name** | **New name** | **Notes** |
+| ---------------- | --------------- | ------------ | ------------ | --------- |
+| [stg_facebook_ads__demographics_country](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_country) | New Model |   |   |  Uses `demographics_country` source table  |
+| [stg_facebook_ads__demographics_country_tmp](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_country_tmp) | New Model |   |   | Uses `demographics_country` source table   |
+| [stg_facebook_ads__demographics_country_actions](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_country_actions) | New Model |   |   |  Uses `demographics_country_actions` source table  |
+| [stg_facebook_ads__demographics_country_actions_tmp](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_country_actions_tmp) | New Model |   |   | Uses `demographics_country_actions` source table   |
+| [stg_facebook_ads__demographics_region](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_region) | New Model |   |   |  Uses `demographics_region` source table  |
+| [stg_facebook_ads__demographics_region_tmp](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_region_tmp) | New Model |   |   | Uses `demographics_region` source table   |
+| [stg_facebook_ads__demographics_region_actions](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_region_actions) | New Model |   |   |  Uses `demographics_region_actions` source table  |
+| [stg_facebook_ads__demographics_region_actions_tmp](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__demographics_region_actions_tmp) | New Model |   |   | Uses `demographics_region_actions` source table   |
+| [stg_facebook_ads__account_history](https://fivetran.github.io/dbt_facebook_ads_source/#!/model/model.facebook_ads_source.stg_facebook_ads__account_history) | New Columns |   | `business_state`, `timezone_offset_hours_utc`, `min_daily_budget`  |  |
+
+## Feature Updates:
+- Added the `facebook_ads__using_demographics_country` and `facebook_ads__using_demographics_region` variables, which can be used to enable or disable the above transformations related to the `demographics_country`/`demograhics_country_actions` and `demographics_region`/`demographics_region_actions` tables.
+  - These variables are dynamically set for Fivetran Quickstart users, but **false** by default otherwise. See [README](https://github.com/fivetran/dbt_facebook_ads_source?tab=readme-ov-file#enable-or-disable-country-and-region-reports) for more details on how to enable these models, particularly if you are using dbt Core.
+- Introduced the following passthrough column variables, which can be used to pass through additional metrics fields from their respective source reports to downstream models. See [README](https://github.com/fivetran/dbt_facebook_ads_source?tab=readme-ov-file#passing-through-additional-metrics) for more details.
+  - `facebook_ads__demographics_country_passthrough_metrics`
+  - `facebook_ads__demographics_country_actions_passthrough_metrics`
+  - `facebook_ads__demographics_region_passthrough_metrics`
+  - `facebook_ads__demographics_region_actions_passthrough_metrics`
+
 # dbt_facebook_ads_source v0.8.1
 
 ## Bug Fixes

README.md

@@ -32,7 +32,7 @@ To use this dbt package, you must have the following:
 - A **BigQuery**, **Snowflake**, **Redshift**, **PostgreSQL**, or **Databricks** destination.
 - You will need to configure your Facebook Ads connection to pull the `basic_ad` pre-built report and its child `basic_ad_actions` and `basic_ad_action_values` pre-built reports. These pre-built reports should be enabled in your connection by default. However, to confirm these reports are actively syncing you may perform the following steps:
     1. Navigate to the connection schema tab in Fivetran.
-    2. Search for `basic_ad`, `basic_ad_actions`, `basic_ad_action_values` and confirm they all selected/enabled.
+    2. Search for `basic_ad`, `basic_ad_actions`, `basic_ad_action_values` and confirm they all selected/enabled. If you would like country and region-level transformations, do the same for `demographics_country`, `demographics_country_actions`, `demographics_region`, and `demographics_region_actions`.
     3. If not selected, do so and sync. If already selected you are ready to run the models!
 
  >**Note**: If you do not have your Facebook Ads connection [schema change settings](https://fivetran.com/docs/using-fivetran/features/data-blocking-column-hashing/config#configureschemachangesettingsforexistingconnectors) set to `Allow all`, it is possible that you are missing `basic_ad_actions` or `basic_ad_action_values`. If you would like to surface conversion metrics in your Facebook and/or Ad Reporting models, please ensure these reports are syncing. Otherwise, the `conversions` and `conversions_value` fields will be `null`.
@@ -51,7 +51,7 @@ If you are not using the [Facebook Ads](https://github.com/fivetran/dbt_facebook
 ```yml
 packages:
   - package: fivetran/facebook_ads_source
-    version: [">=0.8.0", "<0.9.0"] # we recommend using ranges to capture non-breaking changes automatically
+    version: [">=0.9.0", "<0.10.0"] # we recommend using ranges to capture non-breaking changes automatically
 ```
 ### Step 3: Define database and schema variables
 By default, this package runs using your destination and the `facebook_ads` schema. If this is not where your Facebook Ads data is (for example, if your facebook_ads schema is named `facebook_ads_fivetran`), add the following configuration to your root `dbt_project.yml` file:
@@ -77,8 +77,21 @@ 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.
 
+#### Enable or Disable Country and Region Reports
+This package uses the `demographics_country`, `demographics_country_actions`, `demographics_region`, and `demographics_region_actions` [pre-built](https://fivetran.com/docs/connectors/applications/facebook-ads/prebuilt-reports) reports, but takes into consideration that not every user may use these tables.
+
+If you are running the Facebook Ads transform package via Fivetran Quickstart, transformations of the above tables will be dynamically enabled or disabled. Otherwise, transformations of these tables are **disabled** by default.
+
+To enable transformations of the above geo-focused reports, add the following variable configurations to your root `dbt_project.yml` file:
+
+```yml
+vars:
+  facebook_ads__using_demographics_country: True # False by default. Will enable/disable use of the `demographics_country` and `demographics_country_actions` reports
+  facebook_ads__using_demographics_region: True # False by default. Will enable/disable use of the `demographics_region` and `demographics_region_actions` reports
+```
+
 #### Passing Through Additional Metrics
-By default, this package will select `clicks`, `impressions`, `cost`, and conversion `value` (using the [default](https://fivetran.com/docs/connectors/applications/facebook-ads/custom-reports#attributionwindows) attribution window) from the source reporting tables (`BASIC_AD`, `BASIC_AD_ACTIONS`, and `BASIC_AD_ACTION_VALUES`) 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`) 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`, `reach`, `frequency`, and conversion `value` (using the [default](https://fivetran.com/docs/connectors/applications/facebook-ads/custom-reports#attributionwindows) attribution window) from the source reporting tables (`BASIC_AD`, `BASIC_AD_ACTIONS`, `BASIC_AD_ACTION_VALUES`, `DEMOGRAPHICS_COUNTRY`, `DEMOGRAPHICS_REGION`, `DEMOGRAPHICS_COUNTRY_ACTIONS`, and `DEMOGRAPHICS_REGION_ACTIONS`) 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`) 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
 vars:
@@ -97,6 +110,14 @@ vars:
       - name: "_7_d_click"
         alias: "conversion_value_7d_click"
       - name: "inline"
+    facebook_ads__demographics_country_passthrough_metrics: # Add metrics from DEMOGRAPHICS_COUNTRY
+      - name: "inline_link_clicks"
+    facebook_ads__demographics_country_actions_passthrough_metrics: # Add conversion metrics from DEMOGRAPHICS_COUNTRY_ACTIONS
+      - name: "inline"
+    facebook_ads__demographics_region_passthrough_metrics: # Add metrics from DEMOGRAPHICS_REGION
+      - name: "cost_per_inline_link_click"
+    facebook_ads__demographics_region_actions_passthrough_metrics: # Add conversion metrics from DEMOGRAPHICS_REGION_ACTIONS
+      - name: "inline"
 ```
 
 >**Note** Please ensure you exercised due diligence when adding metrics to these models. The metrics added by default (taps, impressions, spend, and default-attribution window conversion values) 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.

dbt_project.yml

@@ -1,5 +1,5 @@
 name: 'facebook_ads_source'
-version: '0.8.1'
+version: '0.9.0'
 config-version: 2
 require-dbt-version: [">=1.3.0", "<2.0.0"]
 models:
@@ -18,7 +18,15 @@ vars:
     basic_ad_action_values: "{{ source('facebook_ads','basic_ad_action_values') }}"
     campaign_history: "{{ source('facebook_ads','campaign_history') }}"
     creative_history: "{{ source('facebook_ads','creative_history') }}"
+    demographics_country: "{{ source('facebook_ads', 'demographics_country') }}"
+    demographics_country_actions: "{{ source('facebook_ads', 'demographics_country_actions') }}"
+    demographics_region: "{{ source('facebook_ads', 'demographics_region') }}"
+    demographics_region_actions: "{{ source('facebook_ads', 'demographics_region_actions') }}"
 
   facebook_ads__basic_ad_passthrough_metrics: []
   facebook_ads__basic_ad_actions_passthrough_metrics: []
-  facebook_ads__basic_ad_action_values_passthrough_metrics: []
+  facebook_ads__basic_ad_action_values_passthrough_metrics: []
+  facebook_ads__demographics_country_passthrough_metrics: []
+  facebook_ads__demographics_country_actions_passthrough_metrics: []
+  facebook_ads__demographics_region_passthrough_metrics: []
+  facebook_ads__demographics_region_actions_passthrough_metrics: []

integration_tests/dbt_project.yml

@@ -1,12 +1,17 @@
 name: 'facebook_ads_source_integration_tests_2'
-version: '0.8.1'
+version: '0.9.0'
 profile: 'integration_tests'
 config-version: 2
 
 models:
   +schema: "facebook_ads_source_{{ var('directed_schema','dev') }}"
 
 vars:
+  # Comment IN docs generate
+  # facebook_ads__using_demographics_country: true
+  # facebook_ads__using_demographics_region: true
+
+  # Comment OUT for docs generation
   facebook_ads__basic_ad_passthrough_metrics:
     - name: "reach"
     - name: "frequency"
@@ -32,6 +37,10 @@ vars:
     facebook_ads_basic_ad_action_values_identifier: "facebook_ads_basic_ad_action_values_data"
     facebook_ads_campaign_history_identifier: "facebook_ads_campaign_history_data"
     facebook_ads_creative_history_identifier: "facebook_ads_creative_history_data"
+    facebook_ads_demographics_country_identifier: "facebook_ads_demographics_country_data"
+    facebook_ads_demographics_country_actions_identifier: "facebook_ads_demographics_country_actions_data"
+    facebook_ads_demographics_region_identifier: "facebook_ads_demographics_region_data"
+    facebook_ads_demographics_region_actions_identifier: "facebook_ads_demographics_region_actions_data"
 
 seeds:
   facebook_ads_source_integration_tests_2:
@@ -52,7 +61,15 @@ seeds:
         inline: "float"
         _1_d_view: "float"
         _7_d_click: "float"
-
+    facebook_ads_demographics_country_actions_data:
+      +column_types:
+        value: "float"
+    facebook_ads_demographics_region_actions_data:
+      +column_types:
+        value: "float"
+  +docs:
+    show: false
+
 dispatch:
   - macro_namespace: dbt_utils
     search_order: ['spark_utils', 'dbt_utils']

integration_tests/requirements.txt

@@ -5,3 +5,4 @@ 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.6.0,<2.0.0
+certifi==2025.1.31

integration_tests/seeds/facebook_ads_demographics_country_actions_data.csv

@@ -0,0 +1,11 @@
+_fivetran_id,_fivetran_synced,account_id,action_type,date,index,inline,value
+e5a9c0f9b52b4ef99a4dd2d72b9efb21,2025-04-20 10:00:00,1700252260223815,lead,2025-04-10,1,10.0,100.0
+c2ef6b2c5b7248dcbb9a6a219e9d9a72,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-11,2,15.5,200.0
+b8dfb4299d0646d1988f726a5a67e9f4,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-12,3,20.0,300.0
+fd4e5c8b1eec4f0292bd5f1b9b6e73e7,2025-04-20 10:00:00,1700252260223815,lead,2025-04-13,4,8.3,120.0
+93c2e601d2b94060a38a8f6e97f8aa67,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-14,5,17.2,210.0
+a7d6f5b3f5e84172af70a6cb6c7a6b80,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-15,6,22.5,400.0
+14cf3d376f744d13b1b871df78f5ed92,2025-04-20 10:00:00,1700252260223815,lead,2025-04-16,7,12.0,140.0
+6eb6c9d107054ab2b5aeeb09cc189476,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-17,8,19.3,250.0
+f32a3b81f7c54b64a1ab62239d162a68,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-18,9,25.0,500.0
+1c8c8cf0d7f8474d90cf5f7d279cfcaf,2025-04-20 10:00:00,1700252260223815,lead,2025-04-19,10,9.8,115.0

integration_tests/seeds/facebook_ads_demographics_country_data.csv

@@ -0,0 +1,11 @@
+_fivetran_id,_fivetran_synced,account_id,country,date,frequency,impressions,inline_link_clicks,reach,spend
+ce51b8e0a0cb4f1e90bb570646fe0736,2025-04-20 10:00:00,1700252260223815,US,2025-04-10,1.5,1500,120,1000,45.30
+d8e6b51e65b042c08487c5d17c70e7bc,2025-04-20 10:00:00,1700252260223815,CA,2025-04-11,1.2,1200,90,980,32.75
+a7cf93f2dbd847ff80ac1b46cf25ed71,2025-04-20 10:00:00,1700252260223815,GB,2025-04-12,2.0,2000,210,1000,76.20
+ff9056d5c4ab4204a931d5364426c00c,2025-04-20 10:00:00,1700252260223815,AU,2025-04-13,1.7,1700,110,1300,54.60
+cc47667c65ef48abbb870a6cb9be89cd,2025-04-20 10:00:00,1700252260223815,IN,2025-04-14,1.3,1300,100,1100,29.99
+f31c9b35f882442c9492959ec7e62345,2025-04-20 10:00:00,1700252260223815,DE,2025-04-15,1.6,1600,140,1200,47.25
+de5d19a443cd41efb1040d244a91aa70,2025-04-20 10:00:00,1700252260223815,FR,2025-04-16,1.9,1900,180,1150,66.40
+3e540428b5c74224bc3e741fa9a66f20,2025-04-20 10:00:00,1700252260223815,JP,2025-04-17,1.4,1400,95,980,36.10
+ea3a462107694ce7a47e0f83d295a654,2025-04-20 10:00:00,1700252260223815,BR,2025-04-18,2.1,2100,160,1000,72.88
+1ff1b1ea44164f38ad18745fc7acb9db,2025-04-20 10:00:00,1700252260223815,MX,2025-04-19,1.1,1100,85,900,28.50

integration_tests/seeds/facebook_ads_demographics_region_actions_data.csv

@@ -0,0 +1,11 @@
+_fivetran_id,_fivetran_synced,account_id,action_type,date,value
+a7b9c0e5d1e946dbb4d1d3f63e9dfaf3,2025-04-20 10:00:00,1700252260223815,lead,2025-04-10,100.0
+c6f41d1a9acb4f32a109fb4e9a7f7490,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-11,150.0
+fd04f1f9eebc43f9a5c2260a7b9c7e9f,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-12,200.0
+b13a40b093ae491d9f5c346bb932ff25,2025-04-20 10:00:00,1700252260223815,lead,2025-04-13,120.0
+81e6fc9247d74e7993bcf6104237f0c5,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-14,175.0
+67e72aa6a1a949c49f76f6b6f46c4255,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-15,300.0
+04b00b9ddf1c4b6a9f26e5df8e8be351,2025-04-20 10:00:00,1700252260223815,lead,2025-04-16,130.0
+1b1c64b780bc412c93cf71680d4c3c8e,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_lead,2025-04-17,190.0
+9a4d2a4bdf6749a280ecde34be9e72f6,2025-04-20 10:00:00,1700252260223815,offsite_conversion.fb_pixel_purchase,2025-04-18,400.0
+eece7c879d6d4593ae1eb0f3f5c8e979,2025-04-20 10:00:00,1700252260223815,lead,2025-04-19,110.0

integration_tests/seeds/facebook_ads_demographics_region_data.csv

@@ -0,0 +1,11 @@
+_fivetran_id,_fivetran_synced,account_id,date,frequency,impressions,inline_link_clicks,reach,region,spend
+e76b8fc5e74b456e8ecb062b3f82f8a2,2025-04-20 10:00:00,1700252260223815,2025-04-10,1.3,1300,105,980,California,42.10
+c1497c7c3c1e4e1e8bc89d116e4e127e,2025-04-20 10:00:00,1700252260223815,2025-04-11,1.6,1600,98,1150,Ontario,53.75
+b90d8c89f3f348299f0ebffb81901468,2025-04-20 10:00:00,1700252260223815,2025-04-12,1.4,1400,110,1000,Texas,39.90
+fef40a4e77e24496ad2e2d090960a158,2025-04-20 10:00:00,1700252260223815,2025-04-13,1.7,1700,120,1300,Quebec,48.30
+8dcb2dc4c8124868b0f422e9c55c3dfb,2025-04-20 10:00:00,1700252260223815,2025-04-14,1.5,1500,99,1020,Florida,36.85
+a1d3c6b8bdf84020ac13e2f7e6c33cf8,2025-04-20 10:00:00,1700252260223815,2025-04-15,1.8,1800,140,1400,British Columbia,57.60
+d2f1d94f48734dfd85d4ce67a653b3fa,2025-04-20 10:00:00,1700252260223815,2025-04-16,1.2,1200,85,950,New York,33.25
+e53a967b8d6c41a1b31d5c64951234cb,2025-04-20 10:00:00,1700252260223815,2025-04-17,2.0,2000,160,1200,Alberta,62.40
+fc1a8cbee7a54f83903bbdf49821c309,2025-04-20 10:00:00,1700252260223815,2025-04-18,1.9,1900,150,1100,Illinois,59.90
+93df7f3f5e92464e87e2c8e94746cbce,2025-04-20 10:00:00,1700252260223815,2025-04-19,1.1,1100,70,870,New South Wales,28.70

macros/get_account_history_columns.sql

@@ -8,7 +8,10 @@
     {"name": "business_country_code", "datatype": dbt.type_string()},
     {"name": "created_time", "datatype": dbt.type_timestamp()},
     {"name": "currency", "datatype": dbt.type_string()},
-    {"name": "timezone_name", "datatype": dbt.type_string()}
+    {"name": "timezone_name", "datatype": dbt.type_string()},
+    {"name": "timezone_offset_hours_utc", "datatype": dbt.type_float()},
+    {"name": "business_state", "datatype": dbt.type_string()},
+    {"name": "min_daily_budget", "datatype": dbt.type_int()}
 ] %}
 
 {{ return(columns) }}