Essential Resources for Migrating Google Ads Scripts to the New Scripts Experience (GAQL)

October 31, 2022, was the date marked by Google to automatically migrate all scripts from an account to the new script experience (new scripts experience, in its original language).

However, the adaptation of scripts has presented many more difficulties than Google expected and, after the deadline, the old scripts are still operational. One only needs to take a look at the Google support forum to understand the magnitude of the problems they are encountering.

In any case, sooner or later the migration will be completed, and the old scripts will stop running correctly. To assist anyone mired in this process, we focus here on compiling some of Google’s help pages vital for carrying out the transition.

What is different about the New Scripts Experience?

The new scripting infrastructure for Google Ads is based on the Google Ads API. Due to the different architecture of this API, most of the scripts we are using will generate errors during execution, and it is necessary to update them.

Google has sought to ensure the greatest possible backward compatibility, so these changes should be minor, although, in practice, they can be very cumbersome considering the wide variety of errors that migration is generating.

Some reports programmed in the old AWQL language may continue to work. By using the new infrastructure, scripts are designed to adapt a query from AWQL to GAQL (Google Ads Query Language, the new query language for the Google Ads API), to run it on the new backend and convert the results to the format originally used by AWQL. GAQL queries undergo no transformation.

Because of this, it is recommended to review all scripts and update AWQL queries to GAQL whenever possible. Google has designed a query migration tool that uses the same logic as the scripts to construct a GAQL query for an AWQL query.

An interactive query generator can also be used to help build queries. Below we include these tools, along with some observations that we find appropriate.

However, there are some limitations to the automatic translation from AWQL to GAQL:

Not all AWQL queries translate cleanly to GAQL queries. In these cases, when using the migration tool, an error message will be displayed with some details about what went wrong, to help you fix it manually.
Not all AWQL report types are compatible with GAQL.
GAQL does not support “zero impression rows.” Specifying that a report should include zero impressions will generate an error.
Some ambiguous fields cannot be used in filters. For example, “Title” could refer to a multitude of different advertising fields.
Some fields may return results in a different format, for example, splitting a result into several columns.

Here are a couple of examples of transforming a query from AQGL to GAQL:

# AWQL

SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT DURING LAST_7_DAYS

# Google Ads Query Language (GAQL)
SELECT campaign.id, ad_group.id, metrics.impressions, metrics.clicks, metrics.cost_micros
FROM ad_group
WHERE segments.date DURING LAST_7_DAYS

# AWQL
SELECT CampaignName, CampaignStatus, Device, Impressions, Clicks
FROM CAMPAIGN_PERFORMANCE_REPORT DURING LAST_30_DAYS

# Google Ads Query Language (GAQL)
SELECT campaign.name, campaign.status, segments.device, metrics.impressions,metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

More examples: https://developers.google.com/google-ads/api/docs/reporting/example

For more generic information about migration.

Some of the advantages of the new infrastructure are:

Support for ES6, a more modern version of JavaScript.
Allows processing more entities (keywords, ads, ad groups, campaigns, labels) in the same amount of time.
Define bidding strategies, even with strategies that require an additional parameter (such as target ROAS or target impression share).
Improvement in the script validation process.

Essential resources for migrating Google Ads Scripts to the New Scripts Experience

Let’s address the section that might be of most interest. We are offering this compilation due to the difficulty we faced in finding the correct information during the migration of our scripts. I hope that if you are in the same desperate process, it may prove very useful to you.

NOTE: If the following links lead you to a Google Service Unavailable page, reloading the page should make the content available.

To begin with, here you will find an article with a good introduction to the different types of queries that can be performed in the scripts with GAQL and it includes a couple of interesting videos that also lead you to the official YouTube channel of GAds Developers, where other useful resources can be found:

Google Ads Query Language

We mentioned it before, but a key page in migrating Scripts to the new experience is the query migration tool. The following tool can be used to translate AWQL queries to GAQL. If for some reason it appears as unavailable in your browser, I recommend trying in incognito mode.

Query Migration Tool

This page offers an extraordinarily useful list with the equivalence of all the resources available in the old AdWords API and in the new Google Ads API. This page is of great value when converting old queries to the new language.:

Resource Mappings

Here you will find the list of available resources that can be used in the scripts’ queries in the FROM clause (ad_group, ad_group_ad, campaign, keyword_view, bidding_strategy in summary, all), with a very useful description of each resource:

Google Ads Query Builder

A very powerful tool is the following Google Ads Query Builder, which allows us to construct queries for each of the available resources (included in the link above) for each of the Query fields (SELECT, WHERE, ORDER BY, LIMIT, and PARAMETERS) from dropdowns that exclusively show us the valid elements for that specific query. The following link leads you to the accessible_bidding_strategy resource but on the left sidebar, you can find the resource that interests you.

Google Ads Query Builder

Complementing the previous one, we find the query validator: It allows you to enter a query and submit it. If the entered query is valid, you can continue editing using the interactive query builder. Otherwise, you are presented with a list of errors, which can be progressively corrected to create a valid GAQL query.

Google Ads Query Builder (Validator)

Just like in the old Scripts experience, we also have available a detailed listing of each one of the available fields (metrics, segments, and resources) for each report. For example, in the following link, we have the page equivalent to the Keyword_Performance_Report, now Keyword_view.

On this page, all metrics and segments that can be placed in the SELECT clause for a keyword_view query are displayed. However, when using keyword_view in the FROM clause, some metrics and segments cannot be used. Using the filter that appears under general information, only the fields available when specifying keyword_view in the FROM clause are displayed.

It is crucial to consider that the list of operators in the WHERE clause is different. In the following article, a detailed list of valid operators is shown, as well as those that cease to be functional:

Querying in the Google Ads API

We hope you find these resources helpful. You can share with us your difficulties with migration, and let’s make this task less arduous together.

Essential Resources for Migrating Google Ads Scripts to the New Scripts Experience (GAQL)

What is different about the New Scripts Experience?

Essential resources for migrating Google Ads Scripts to the New Scripts Experience

MOST RECENT ARTICLES

How to Implement Consent Mode v2 and Not Die Trying

New cookie regulations and Consent Mode v2: The Phantom Menace

Microsoft Ads Scripts: A Hidden Gem of Digital Marketing