Release Notes

August 2026

v1.5.1

Feature Updates

• Adds DuckDB as a supported destination.

June 2026

v1.5.0

Schema/Data Changes (--full-refresh required after upgrading)

1 total change • 1 possible breaking change

Feature Updates

• Introduces the new (recommended) facebook_ads_sources variable for more robust union data configuration. The oldfacebook_ads_union_schemas and facebook_ads_union_databases variables will still be supported. See the README for specific details.

Under the Hood

• Adds the fivetran_using_source_casing variable for case-sensitive destination support. When enabled, downstream transformations respect source casing to ensure consistent results. See the Additional Configurations section of the README for details.
• Introduces fivetran_utils.partition_by_source_relation to conditionally include source_relation in partition clauses only when multiplesources are configured.

March 2026

v1.4.1

Bug Fix

• Updates URL tag processing to handle native JSON datatypes across all supported warehouses, preventing errors when url_tags columns are stored as JSON/JSONB/VARIANT/SUPER instead of strings.

Feature Update

• Adds the get_column_datatype() macro to retrieve the datatype of a specific column.
• Updates the get_url_tags_query() macro with datatype detection to handle both native JSON columns and JSON-like string columns across BigQuery (JSON), Snowflake (VARIANT), Redshift (SUPER), and PostgreSQL (JSONB).

Under the Hood

• Adds native JSON testing to integration_tests.
• Updates the vertical_sum_conversion_value integrity test to validate both conversions_value and conversions.

v1.4.2

Bug Fix

• Fixes PostgreSQL compatibility issue in get_url_tags_query() macro where jsonb columns were incorrectly processed using json_array_elements() instead of jsonb_array_elements(), causing database errors when url_tags column is stored as jsonb datatype.

January 2026

v1.3.0

Schema/Data Change

10 total changes • 0 possible breaking changes

The default action types included are onsite_conversion.purchase, onsite_conversion.lead_grouped, offsite_conversion.fb_pixel_purchase, offsite_conversion.fb_pixel_lead, and offsite_conversion.fb_pixel_custom. You can add additional custom action types by configuring the facebook_ads__conversion_action_types variable. See the README for details on how to configure custom action types.

Under the Hood

• Adds facebook_action_slug macro to generate slugified column names from action type configurations.

v1.4.0

Documentation

• Updates README with standardized Fivetran formatting.
• Removes duplicative column yml definitions.

Under the Hood

• In the quickstart.yml file:
  • Adds table_variables for relevant sources to prevent missing sources from blocking downstream Quickstart models.
  • Adds supported_vars for Quickstart UI customization.

August 2025

v1.0.0

Breaking Changes

Source Package Consolidation

• Removed the dependency on the fivetran/facebook_ads_source package.
  • All functionality from the source package has been merged into this transformation package for improved maintainability and clarity.
  • If you reference fivetran/facebook_ads_source in your packages.yml, you must remove this dependency to avoid conflicts.
  • Any source overrides referencing the fivetran/facebook_ads_source package will also need to be removed or updated to reference this package.
  • Update any facebook_ads_source-scoped variables to be scoped to only under this package. See the README for how to configure the build schema of staging models.
• As part of the consolidation, vars are no longer used to reference staging models, and only sources are represented by vars. Staging models are now referenced directly with ref() in downstream models.

dbt Fusion Compatibility Updates

• Updated package to maintain compatibility with dbt-core versions both before and after v1.10.6, which introduced a breaking change to multi-argument test syntax (e.g., unique_combination_of_columns).
• Temporarily removed unsupported tests to avoid errors and ensure smoother upgrades across different dbt-core versions. These tests will be reintroduced once a safe migration path is available.
  • Removed all dbt_utils.unique_combination_of_columns tests.
  • Moved loaded_at_field: _fivetran_synced under the config: block in src_facebook_ads.yml.

Under the Hood

• Updated conditions in .github/workflows/auto-release.yml.
• Added .github/workflows/generate-docs.yml.

v1.1.0

Schema Updates

4 total changes • 0 possible breaking changes

Documentation

• Updated fivetran_id and index definitions to highlight importance in determining Fivetran key.

Under the Hood

• Removed second reviewer workflow, as it's not longer being implemented.

November 2024

v0.8.0

Feature Updates: Conversion Metrics

PR #43 includes the following updates:

• Adds a conversions and conversions_value field to each _report end model, representing the raw and monetary value of conversions, respectively, that occurred on each day for each ad/campaign/ad set/url/account. These will aggregate conversions of all included action_types.
  • By default, the package will consider purchase, lead, and custom-defined events to be conversions based on the record's action_type (see below):

• The above can be configured via the the new facebook_ads__conversion_action_types variable. See README for more details.

### dbt_project.yml
vars:
  facebook_ads__conversion_action_types: # case-insensitive
    - name: exact_conversion_action_type_name # will grab `basic_ad_actions` records where action_type = 'exact_conversion_action_type_name'
    - pattern: onsite_conversion% # will grab all `onsite_conversion%` records
    - name: offsite_conversion.custom.my_custom_conversion_123
    - name: very_specific_conversion_action
      where_sql: source_relation = 'specific advertiser source' # will grab `basic_ad_actions` records where (action_type = very_specific_conversion_action and {{ where_sql }})
    - pattern: subscribe%
      where_sql: source_relation = 'advertiser who only cares about subscriptions' # will grab `basic_ad_actions` records where (action_type like 'subscribe%' and {{ where_sql }})

Note: If you were previously utilizing the facebook_ads__basic_ad_passthrough_metrics variable to include a (likely null) field called conversions or conversions_value, the package's version of these fields will take precedence over yours. To continue including your old conversions fields, change the alias of the passthrough field to another name.

• Creates the new facebook_ads__basic_ad_actions_passthrough_metrics and facebook_ads__basic_ad_action_values_passthrough_metrics variables to pass through additional conversion value metrics that are calculated using different attribution windows.
  • By default, the package includes only the conversion values calculated using the default attribution window set in Meta, but your report may include calculations using the other windows defined here. See README for details on how to use the new variables.
• Adds optimization_goal field to facebook_ads__ad_set_report model. This is defined as the optimization goal this ad set is using, possible values of which are defined here.
• Adds conversion_domain field to facebook_ads__ad_report model. This is defined as the domain you've configured the ad to convert to.

Documentation

• Documents the ability to transform metrics provided to the facebook_ads__basic_ad_passthrough_metrics and facebook_ads__basic_ad_action_values_passthrough_metrics variables. See README for details (PR #43).
• Added missing documentation for fields in the campaign, ad set, and account report models (PR #43).

Under the Hood

• Updated the quickstart.yml file to allow for automated Quickstart data model deployments (PR #40).
• Updated the PR templates to align with our most up-to-date standards (PR #43).
• Removed the now-defunct 2nd reviewer bot workflow (PR #43).
• Added a new version of the persist_pass_through_columns() macro in which we can include coalesces and exclusion fields. (PR #43).
  • This macro will sum together any passthrough columns and cast them as floats.
• Updated the quickstart.yml file to allow for automated Quickstart data model deployments. (PR #40)