Google Ads Migration Guide

Availability

Core Standard Plus Pro Enterprise Flex Self-Managed Enterprise PyAirbyte

Support Level

Airbyte

Connector Version

4.2.6 (last updated 13 days ago)

CDK Version

7.18.1.post8.dev25490693965

Sync Success Rate

Usage Rate

Definition ID

253487c0-2246-43ba-a21f-5116b20a2c50

Upgrading to 5.0.0

This release combines two breaking changes:

1. The Google Ads API is upgraded from Version 20 to Version 23 (see key changes below).
2. The nullable bidding_strategy.id field is removed from primary keys. See the table below for new primary keys.

Google Ads API v23 changes

Key changes include:

• New segments.ad_network_type support for Performance Max campaigns (channel-level reporting)
• Renamed deprecated video metrics to TrueView equivalents
• Removed CallAd and CallAdInfo fields from ad_group_ad schema
• Renamed campaign date fields to datetime equivalents
• Removed lead_form_only field from DemandGenMultiAssetAdInfo
• Removed aggregate asset performance label metrics

The following field renames and removals affect built-in stream schemas:

Stream	Previous field name	New field name
account_performance_report	metrics.average_cpv	metrics.trueview_average_cpv
account_performance_report	metrics.video_view_rate	metrics.video_trueview_view_rate
account_performance_report	metrics.video_views	metrics.video_trueview_views
ad_group_ad	ad_group_ad.ad.call_ad.* / CallAdInfo fields	Removed
ad_group_ad_legacy	metrics.average_cpv	metrics.trueview_average_cpv
ad_group_ad_legacy	metrics.video_view_rate	metrics.video_trueview_view_rate
ad_group_ad_legacy	metrics.video_views	metrics.video_trueview_views
campaign	campaign.start_date	campaign.start_date_time
campaign	campaign.end_date	campaign.end_date_time
campaign	metrics.video_views	metrics.video_trueview_views
campaign_budget	metrics.average_cpv	metrics.trueview_average_cpv
campaign_budget	metrics.video_view_rate	metrics.video_trueview_view_rate
campaign_budget	metrics.video_views	metrics.video_trueview_views
display_keyword_view	metrics.average_cpv	metrics.trueview_average_cpv
display_keyword_view	metrics.video_view_rate	metrics.video_trueview_view_rate
display_keyword_view	metrics.video_views	metrics.video_trueview_views
geographic_view_with_metrics	metrics.average_cpv	metrics.trueview_average_cpv
geographic_view_with_metrics	metrics.video_view_rate	metrics.video_trueview_view_rate
geographic_view_with_metrics	metrics.video_views	metrics.video_trueview_views
topic_view	metrics.average_cpv	metrics.trueview_average_cpv
topic_view	metrics.video_view_rate	metrics.video_trueview_view_rate
topic_view	metrics.video_views	metrics.video_trueview_views
user_location_view	metrics.average_cpv	metrics.trueview_average_cpv
user_location_view	metrics.video_view_rate	metrics.video_trueview_view_rate
user_location_view	metrics.video_views	metrics.video_trueview_views

The following fields were also removed in v23 and may affect custom queries (custom_queries_array), even though they are not used in built-in streams:

• campaign.url_expansion_opt_out
• ad_group_ad.ad.demand_gen_multi_asset_ad.lead_form_only
• asset_group_asset.performance_label

For custom queries, the stream may fail if a field was removed or renamed during the API update. Users with custom queries that reference any of the renamed or removed fields above must update their queries accordingly. You can use the Query Builder to validate your custom queries.

Primary key change for bidding strategy streams

The bidding_strategy.id field is nullable in the Google Ads API, meaning it can return null values. Including a nullable field in the primary key caused sync failures for destinations that enforce non-null primary key constraints, such as the Iceberg destination.

Stream	Old primary key	New primary key
campaign_bidding_strategy	campaign.id, bidding_strategy.id, segments.date	campaign.id, segments.date
ad_group_bidding_strategy	ad_group.id, bidding_strategy.id, segments.date	ad_group.id, segments.date

Users syncing the campaign_bidding_strategy or ad_group_bidding_strategy streams are affected.

Action required

After upgrading, refresh the source schema and clear data for the affected streams to ensure uninterrupted syncs.

Review the following information to prepare for and execute your upgrade.

Review the changelog

Before updating a connector, review the changelog to understand the changes and their potential impact on your existing connections. Find the changelog for any connector by navigating to the bottom of the documentation for that connector. Major version releases also include a migration guide.

Plan for major updates

Major updates may require you to adjust connection settings or even make changes to your data pipelines. Allocate enough time and resources for this. Use the migration guide to ensure your transition process goes smoothly.

Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You always need to manually update for major version bumps.

Self-managed plans: pin a specific version if you can't update

If you're unable to upgrade to the new version of a connector, you can pin that connector to a specific version.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Edit the entry for the connector you want to pin.

3. Set the Default Version to the version you want to use.

Self-managed plans: update the local connector image

If you self-manage Airbyte, you must manually update the connector image in your local registry before proceeding with the migration. Follow the steps below.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Find the connector you want to update in the list of connectors.

   note

   Airbyte lists two versions, the current in-use version and the latest version available.

3. Click Change to update your OSS version to the latest available version.

Update the connector version

Update each instance of the connector separately. If you have multiple instances of a connector, updating one doesn't affect the others.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Select the instance of the connector you wish to upgrade.

3. Select Upgrade.

4. Follow the prompt to confirm you are ready to upgrade to the new version.

Clear data from affected streams

After upgrading a connector with a breaking change, you must refresh affected schemas and clear your data.

1. In the nav bar, click Connections.

2. Find the connection affected by the upgrade.

3. Click the Schema tab.

4. Click Refresh source schema (looks like ). When Airbyte finishes, it shows you any detected schema changes.

5. Click OK.

6. Click Save changes

7. Clear the data for the streams affected by this upgrade.

Once the clear is complete, you can begin syncing your data again as usual.

Upgrading to 4.0.0

This release upgrades the Google Ads API from Version 18 to Version 20 which causes the following changes in the schemas:

Stream	Current field name	New field name
campaign	campaign.dynamic_search_ads_setting.feeds	This field has been deleted
user_interests	user_interest.availabilities	Updated advertisingChannelSubType enum for the Video channel: removed VIDEO_OUTSTREAM and added YOUTUBE_AUDIO.

For custom queries, the stream may fail if a field was removed during the API update. Additionally, some field values may have changed, such as user_interest.availabilities. You can use the Query Builder to validate your custom queries.

Users should:

• Refresh the source schema
• Reset affected streams after upgrading to ensure uninterrupted syncs.

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 3.0.0

This release upgrades the Google Ads API from Version 13 to Version 15 which causes the following changes in the schemas:

Stream	Current field name	New field name
ad_listing_group_criterion	ad_group_criterion.listing_group.case_value.product_bidding_category.id	ad_group_criterion.listing_group.case_value.product_category.category_id
ad_listing_group_criterion	ad_group_criterion.listing_group.case_value.product_bidding_category.level	ad_group_criterion.listing_group.case_value.product_category.level
shopping_performance_view	segments.product_bidding_category_level1	segments.product_category_level1
shopping_performance_view	segments.product_bidding_category_level2	segments.product_category_level2
shopping_performance_view	segments.product_bidding_category_level3	segments.product_category_level3
shopping_performance_view	segments.product_bidding_category_level4	segments.product_category_level4
shopping_performance_view	segments.product_bidding_category_level5	segments.product_category_level5
campaign	campaign.shopping_setting.sales_country	This field has been deleted

Users should:

• Refresh the source schema
• Reset affected streams after upgrading to ensure uninterrupted syncs.

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 2.0.0

This release updates the Source Google Ads connector so that its default streams and stream names match the related resources in Google Ads API.

Users should:

• Refresh the source schema
• And reset affected streams after upgrading to ensure uninterrupted syncs.

Upgrading to 1.0.0

This release introduced fixes to the creation of custom query schemas. For instance, the field ad_group_ad.ad.final_urls in the custom query has had its type changed from {"type": "string"} to {"type": ["null", "array"], "items": {"type": "string"}}. Users should refresh the source schema and reset affected streams after upgrading to ensure uninterrupted syncs.