AxDa.GaqlContext 1.0.1

Enhanced Google Ads Query Language for .NET (GAQL-E)

The Enhanced Google Ads Query Language for .NET NuGet package extends the Google Ads Query Language with powerful query clauses and provides high-performance and streamlined capabilities for aggregating and retrieving data from Google Ads servers using the Google Ads API.

With Enhanced Google Ads Query Language for .NET (GAQL-E), you can, for example, send multiple queries in a single batch, switch customer IDs, or add list parameters to GAQL queries. This provides you with the flexibility to submit multiple GAQL queries within a single GAQL-E query and retrieve the aggregated results.

GAQL-E is backward compatible with GAQL, allowing you to use any standard GAQL query as usual.

Version Information

This version of Enhanced Google Ads Query Language for .NET binds to NuGet package Google.Ads.GoogleAds, version 24.0.1, providing Google Ads API version 21 services.

How to use

This packages centralizes access to the Google Ads API using the GetAsync() method in the GaqlAccessor class. The GetAsync() method accepts an GAQL-E query and returns a collection of SearchGoogleAdsResponse objects resulting from deriving one or more GAQL queries from the specified GAQL-E source query and sending them to Google Ads servers.

Querying data from Google Ads using Enhanced Google Ads Query Language for .NET is quick and straightforward. Just provide a GAQL-E query string along with a customer ID, Google Ads authentication data and an exception handling delegate to the GetAsync() method and await the result:

Task<List<SearchGoogleAdsResponse>> GetAsync
  ( string gaqlQuery
  , string adsCustomerId
  , GoAdsConfig adsAuthConfig
  , ExceptionHandler exceptionHandler
  )

The return value is a collection of SearchGoogleAdsResponse objects (one for each GAQL query derived from the specified GAQL-E source query), each containing a collection of GoogleAdsRow objects.

Optionally, if you want the GetAsync() method to log the Google Ads server traffic, e.g., for debugging purposes, provide the file path to a log file:

Task<List<SearchGoogleAdsResponse>> GetAsync
  ( string gaqlQuery
  , string adsCustomerId
  , GoAdsConfig adsAuthConfig
  , ExceptionHandler exceptionHandler
  , string? logFilePath
  )

You can also pass a callback delegate for reporting progress and a CancellationToken struct as arguments to the GetAsync() method. The progress delegate is invoked each time before a GAQL query compiled from the specified GAQL-E source query is sent to the Google Ads servers.

To authenticate, provide credentials either for OAuth2 web/application flow or a service flow. Google suggests that OAuth2 service flow is preferred.

Providing Google Ads authentication data comprises the following parts:

• A Google developer token
• One of …
  • A Google service account if you are using OAuth2 service flow
  • Google interactive credentials if you are using OAuth2 web/application flow
• A Google Ads customer ID
• The MMC's customer ID (if your customer ID is not an MMC account)

Example

The following example retrieves Google Ads data using the OAuth2 service flow.

It consists of two parts:

1. An exception handler, which is called when a GAQL query triggers an exception.

   The exception handler is mandatory. It returns true to continue execution with the next GAQL query in the batch, or false to stop.

2. An asynchronous call to the GaqlAccessor.GetAsync() method, which compiles the GAQL-E query and retrieves data from the Google Ads servers.

// exeption handler implementation
// to continue query batch execution, return `true`; otherwise `false`
private bool ExceptionHandler(GaqlException exception)
{
  string errorMessage;

  if (exception.InnerException is GoogleAdsException adsException)
  {
    errorMessage = $"{adsException.StatusCode}: {adsException.Status.Detail}";

    if (!errorMessage.EndsWith('.')) errorMessage += '.';

    foreach (GoogleAdsError e in adsException.Failure.Errors)
      errorMessage += Environment.NewLine + Environment.NewLine + e.Message;
  }
  else errorMessage = exception.InnerException?.Message ?? exception.Message;

  // stop batch execution if the error message contains the word "fatal".
  return errorMessage.Contains("fatal", StringComparison.InvariantCultureIgnoreCase);
}


// retrieve campaign data from Google Ads servers
private async Task<string> GetCampaignsAsync(GaqlAccessor gaqlAccessor)
{
  string StringBuilder resultText = new StringBuilder();

  // prepare GAQL-E query
  string query = "SELECT campaign.id, campaign.name FROM campaign";
  string customerId = "123-456-7890", loginCustId = "987-654-3210";
  string develperToken = "AabBcCdD1234EeFfGg";
  Stream oAuthSecretsJson = new FileStream(@"\Path\To\Json\File.json", FileMode.Open);

  OAuth2ServiceCredentials creds = new OAuth2ServiceCredentials(oAuth2SecretsJson);
  GoAdsConfig config = new GoAdsConfig( developerToken
                                      , creds
                                      , loginCustId
                                      );

  // retrieve results
  List<SearchGoogleAdsResponse> result
    = await gaqlAccessor.GetAsync( query
                                 , customerId
                                 , config
                                 , ExceptionHandler
                                 );

  // iterate through all result sets
  foreach (SearchGoogleAdsResponse response in result)
  {
    foreach (GoogleAdsRow row in response) resultText.AppendLine(row.ToString());

    // was the number of rows queried using the GAQL-E "COUNT()" clause?
    if (response.TotalResultsCount >= 0)
      resultText.AppendLine(response.TotalResultsCount.ToString(CultureInfo.InvariantCulture));
  }

  // return data
  return resultText.ToString();
}

Google Ads Query Language Extensions (GAQL-E)

Enhanced Google Ads Query Language for .NET extends the Google Ads query language with powerful additional features:

1. Single line and multi line comments.
2. A USER clause, to set the Google Ads customer ID and login ID within a GAQL query, overriding existing connection values.
3. A COUNT clause, returning the number of data rows to expect from a GAQL query.
4. An OFFSET clause, skipping the specified number of rows.
5. A List Variable feature for running the same query with different parameters in a single batch.
6. A Query Batch feature, allowing to send multiple different queries in a single run.

These new features help prevent buffer overflows or memory exhaustion issues, enable you to retrieve data from multiple customer accounts, and to easily create complex data queries and custom paged data row windows.

<dl> <dt>

Single Line And Multi Line Comment

</dt> <dd>

Comments can be helpful in understanding the intent of a query. Alternatively, you might want to temporarily comment out attributes or WHERE conditions to run tests. With Enhanced Google Ads Query Language for .NET, you can add both single-line and multi-line comments to your queries. Comments are recognized in both SQL and C-style formats.

While single-line comments (either preceded by "--" or "//") extend to the end of a text line, multi-line comments (preceded by "/*") reach until the next multi-line comment terminator ("*/").

Syntax

//  A single-line C-style comment.

/*
    A Multi-line
    C-style comment.
*/

--  A single-line SQL-style comment.

Example

The following GAQL query displays all three supported types of comments:

SELECT
  campaign.name      // A comment on a single line
, campaign.status    -- Another comment on a single line

/* The following two fields are commented out
   and will therefore not be queried:

, campaign.start_date
, campaign.end_date
*/

FROM campaign

</dd>

<dt>

USER clause

</dt> <dd>

With the USER clause you determine the Google Ads customer ID to be used in a query. Its syntax resembles the SQL language USER clause.

Syntax

USER {customer-id} [{,|:|/| } {login-id}|-]

The Google Ads customer ID and login ID may be provided with or without dashes.

The login customer ID (aka. MCC ID) is optional. If not set, the current connection configuration value will be used as login ID.

Login customer ID and customer ID are separated by either a comma (,), a colon (:), a dash (/) or just whitespace character.

If you provide a minus (-) character as login customer ID, then no login customer ID will be used to retrieve data from Google Ads servers for that particular GAQL query, even if the connection configuration specifies a login customer ID.

Examples

The following GAQL query uses customer ID 123-456-7890 for the GAQL query, overriding the current connection configuration value for the customer ID, but retaining the login customer ID value configured in the connection configuration:

USER 132-456-7890
SELECT
  campaign.name
, campaign.status
FROM campaign

<br/>

The following GAQL query uses customer ID 123-456-7890 and login customer ID 987-654-3210 for that particular GAQL query. Both values overide the current connection configuration values:

USER 132-456-7890, 987-654-3210
SELECT
  campaign.name
, campaign.status
FROM campaign

<br/>

The following GAQL query uses customer ID 123-456-7890. No login customer ID will explicitly be used for this GAQL query. Both values overide the current connection configuration values:

USER 132-456-7890 -
SELECT
  campaign.name
, campaign.status
FROM campaign

</dd>

<dt>

COUNT clause

</dt> <dd>

The COUNT clause allows you to query the number of rows of data expected when executing a GAQL query. Its syntax resembles the SQL language COUNT clause.

Syntax

COUNT(resources-list)

In the Google Ads query language, the fields in the resource list determine the number of rows returned. This is especially true for segmentation fields. Therefore, it's necessary to specify all resource fields in the COUNT clause for which you expect to receive the count.

Example

The following GAQL query returns the number of data rows to be expected from the GAQL query:

SELECT COUNT(
  campaign.name
, campaign.status
)
FROM campaign

</dd>

<dt>

OFFSET clause

</dt> <dd>

Use the OFFSET clause to skip the specified number of rows from the result set before returning the remaining rows. In combination with the GAQL LIMIT clause, this allows you to specify paging windows. The OFFSET clause syntax resembles the SQL language OFFSET clause.

Syntax

OFFSET {count}

Example

This following GAQL query returns data rows 20 to 29 from the full result set:

SELECT
  campaign.name
, campaign.status
FROM campaign
OFFSET 20
LIMIT 10

If the result set contains less rows than specified by OFFSET, no rows will be returned.

</dd>

<dt>

FOR ... IN clause

</dt> <dd>

Use the FOR ... IN clause to add parameters to a query.

Using FOR ... IN, you assign a list of values to a variable and have a GAQL query be run for each of the variable's values. The result is a collection of query data rows resulting from each individual GAQL query sent to the Google Ads server for each of the variable values ​​in the list.

Syntax

FOR {variable-name} IN {value} [, {value}]*

A variable name must have a single at-sign ("@") as the first character, followed by a combination of letters, digits and underscores.

Non-token type values (e.g. empty values or values containing other characters than letters, digits or underscore characters) must be quoted, either by a pair of double quotes ("""), single quotes ("'") or backticks ("`"). Quotes will be stripped from the values. If you need quotes around the replaced values in your GAQL query, then add these quotes to the query itself.

FOR ... IN clauses may be nested. This provides for running GAQL queries with a matrix of values.

Examples

The following GAQL query queries data for two different customer IDs:

FOR @user IN 132-456-7890, 987-654-3210
USER @user
SELECT
  campaign.name
, campaign.status
FROM campaign

This is equivalent to the following two GAQL queries:

USER 132-456-7890
SELECT
  campaign.name
, campaign.status
FROM campaign;

USER 987-654-3210
SELECT
  campaign.name
, campaign.status
FROM campaign

<br/>

The following GAQL query queries data for three different dates:

FOR @dates IN 2026-01-01, "2026-02-01", '2026-03-01'
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '@dates'

Note that quotes are removed from variable values. If you need quotes in the GAQL query, you'll need to add them there. In the example above, the segments.date value in the WHERE clause is enclosed in quotes.

The above example is equivalent to the following three GAQL queries:

SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-01-01';

SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-02-01';

SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-03-01'

<br/>

FOR ... IN clauses may be nested. With this feature you can create a matrix of GAQL queries.

The following example queries data for two different customer IDs, for three different dates each:

FOR @dates IN 2026-01-01, "2026-02-01", '2026-03-01'
FOR @user IN 132-456-7890, 987-654-3210
USER @user
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '@dates'

The above example is equivalent to the following six GAQL queries:

USER 132-456-7890
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-01-01';

USER 132-456-7890
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-02-01';

USER 132-456-7890
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-03-01';


USER 987-654-3210
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-01-01';

USER 987-654-3210
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-02-01';

USER 987-654-3210
SELECT
  campaign.name
, campaign.status
FROM campaign
WHERE segments.date = '2026-03-01'

</dd>

<dt>

IMPORT ... FROM clause

</dt> <dd>

While the FOR ... IN clause allows you to load variables with static data written within a GAQL query, the IMPORT ... FROM clause enables dynamic loading of variables with data from external files. This is useful when you have data to be reused across multiple GAQL queries or provided by external data sources.

The result is a collection of query data rows resulting from each individual GAQL query sent to the Google Ads server for each of the values found in the external file.

Syntax

IMPORT {variable-name} FROM {absolute-file-path}

A variable name must have a single at-sign ("@") as the first character, followed by a combination of letters, digits and underscores.

Use absolute file paths for the IMPORT ... FROM clause. Relative file paths are rejected. The file can be located on a local drive or on a UNC network share.

The IMPORT ... FROM clause accepts a comma-separated list of string values as data file content. Single line and multi line comments can also be used in the file. Any other content will be rejected.

In the data file, non-token type values (e.g. empty values or values containing other characters than letters, digits or underscore characters) must be quoted, either by a pair of double quotes ("""), single quotes ("'") or backticks ("`"). Quotes will be stripped from the values. If you need quotes around the replaced values in your GAQL query, then add these quotes to the query itself.

You can use multiple IMPORT ... FROM clauses in your query. This allows you to feed different variables from various sources.

Examples

The following example loads campaigns whose status is specified in an external text file:

The text file path is "C:\Status.txt". The content of the text file is:

ENABLED, PAUSED, REMOVED

The corresponding GAQL query is as follows:

IMPORT @status FROM "C:\Status.txt"
SELECT
  campaign.name
FROM campaign
WHERE campaign.status = @status

The above example is equivalent to the following three GAQL queries:

SELECT
  campaign.name
FROM campaign
WHERE campaign.status = ENABLED;

SELECT
  campaign.name
FROM campaign
WHERE campaign.status = PAUSED;

SELECT
  campaign.name
FROM campaign
WHERE campaign.status = REMOVED

<br/>

The following example loads campaigns whose ID is specified in an external text file. The list of campaigns is further filtered by a FOR ... IN clause.

The text file path is "C:\Campaign IDs.txt". The content of the text file is:

11111111111,
22222222222,
33333333333,
44444444444,
55555555555,
66666666666

The corresponding GAQL query is as follows:

IMPORT @ID FROM "C:\Campaign IDs.txt"
FOR @status in ENABLED, PAUSED
SELECT
  campaign.name
FROM campaign
WHERE campaign.status = @status
  AND campaign.id = @ID

<br/>

The data for the @ID variable could as well have been loaded from an external file. Here is an example that will load campaign status and campaign ID from two external files:

The campaign ID text file path is "C:\Campaign IDs.txt". The content of the text file is:

11111111111,
22222222222,
33333333333,
44444444444,
55555555555,
66666666666

The campaign status text file path is "C:\Status.txt". The content of the text file is:

ENABLED, PAUSED, REMOVED

The corresponding GAQL query is as follows:

IMPORT @ID FROM "C:\Campaign IDs.txt"
IMPORT @status FROM "C:\Status.txt"
SELECT
  campaign.name
FROM campaign
WHERE campaign.status = @status
  AND campaign.id = @ID

</dd>

<dt>

Batch Statement Processing

</dt> <dd>

With Enhanced Google Ads Query Language for .NET , you can provide more than one single GAQL query in the text input field. This extends the returned result set and provides to evaluate a much richer set of data in a single query run.

Another way to look at the batch processing feature is that it acts like a logical OR operator in a WHERE clause. By concatenating multiple GAQL queries with different WHERE clause conditions in a batch, the data from all result sets will be returned.

To use the batch feature and send multiple queries to the Google Ads servers in a single run, separate each query with a semicolon (";") character. The semicolon serves as a query separation marker.

The result is a collection of of data row sets resulting from each individual GAQL query sent to the Google Ads server.

Example

The following batch statement returns campaign name and status for campaigns that are either enabled or paused:

SELECT
  campaign.name
, campaign.status
)
FROM campaign
WHERE campaign.status = ENABLED;

SELECT
  campaign.name
, campaign.status
)
FROM campaign
WHERE campaign.status = PAUSED

Pay careful attention to the trailing semicolon after the first query. The semicolon is not required after the last or only query statement.

Different queries in a batch don't have to address the same resource. You can query any kind of different resources in your queries. </dd> </dl>

Extended GAQL Query Structure

Like the Google Ads query language, this tool's advanced GAQL syntax requires that syntax elements within a query be specified in a fixed order.

A query is made up of the following clauses in the sequence as specified:

No.	Keyword	Mandatory?	Repeatable?
1	IMPORT ... FROM	no	yes
2	FOR ... IN	no	yes
3	USER	no	no
4	SELECT	yes	no
5	COUNT()	no	no
6	FROM	yes	no
7	WHERE	no	no
8	ORDER BY	no	no
9	OFFSET	no	no
10	LIMIT	no	no
11	PARAMETERS	no	no

Feedback, Sponsorship and Contact

You may reach me on axeldahmen.de or LinkedIn