gaql-google-ads-query-language

Google Ads Query Language (GAQL) Guidelines

Overview

The Google Ads Query Language (GAQL) is a powerful tool for querying the Google Ads API that allows you to retrieve:

1. Resources and their related attributes, segments, and metrics using GoogleAdsService.Search or GoogleAdsService.SearchStream
2. Metadata about available fields and resources using GoogleAdsFieldService

Field Categories

Understanding field categories is essential for building effective GAQL queries:

1. RESOURCE: Represents a primary entity (e.g., campaign, ad_group) that can be used in the FROM clause
2. ATTRIBUTE: Properties of a resource (e.g., campaign.id, campaign.name). Including these may segment results depending on the resource relationship
3. SEGMENT: Fields that always segment search queries (e.g., segments.date, segments.device)
4. METRIC: Performance data fields (e.g., metrics.impressions, metrics.clicks) that never segment search queries

Query Structure

A GAQL query consists of the following components:

SELECT
  <field_1>,
  <field_2>,
  ...
FROM <resource>
WHERE <condition_1> AND <condition_2> AND ...
ORDER BY <field_1> [ASC|DESC], <field_2> [ASC|DESC], ...
LIMIT <number_of_results>

SELECT Clause

The SELECT clause specifies the fields to return in the query results:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions,
  segments.device

Only fields that are marked as selectable: true in the GoogleAdsField metadata can be used in the SELECT clause.

FROM Clause

The FROM clause specifies the primary resource type to query from. Only one resource can be specified, and it must have the category RESOURCE.

FROM campaign

WHERE Clause (optional)

The WHERE clause specifies conditions to filter the results. Only fields marked as filterable: true in the GoogleAdsField metadata can be used for filtering.

WHERE 
  campaign.status = 'ENABLED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS