Google Ads Query Language

Query for resource or metadata information

The Google Ads Query Language can query the Google Ads API for the following types of information:

• Resources and their related attributes, segments, and metrics using GoogleAdsService Search or SearchStream : The result from a GoogleAdsService query is a list of GoogleAdsRow instances, with each GoogleAdsRow representing a resource.

  If any attributes or metrics are requested, then the row also includes those fields. If any segments are requested, then the response also shows an additional row for each segment-resource tuple.

• Metadata about available fields and resources in GoogleAdsFieldService : This service provides a catalog of queryable fields with specifics about their compatibility and type.

  The result from a GoogleAdsFieldService query is a list of GoogleAdsField instances, with each GoogleAdsField containing details about the requested field.

Query for resource attributes

Here is an example of a basic query for attributes of the campaign resource that illustrates how to return the campaign ID, name, and status:

  SELECT 
  
 campaign 
 . 
 id 
 , 
  
 campaign 
 . 
 name 
 , 
  
 campaign 
 . 
 status 
 FROM 
  
 campaign 
 ORDER 
  
 BY 
  
 campaign 
 . 
 id 
 

This query orders by campaign ID. Each resulting GoogleAdsRow represents a campaign object populated with the selected fields, including the campaign's resource_name .

To find out what other fields are available for campaign queries, consult the Campaign reference documentation .

Query for metrics

Alongside selected attributes for a given resource, you can also query for related metrics:

  SELECT 
  
 campaign 
 . 
 id 
 , 
  
 campaign 
 . 
 name 
 , 
  
 campaign 
 . 
 status 
 , 
  
 metrics 
 . 
 impressions 
 FROM 
  
 campaign 
 WHERE 
  
 campaign 
 . 
 status 
  
 = 
  
 'PAUSED' 
  
 AND 
  
 metrics 
 . 
 impressions 
 > 
 1000 
 ORDER 
  
 BY 
  
 campaign 
 . 
 id 
 

This query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions, while ordering by campaign ID. Each resulting GoogleAdsRow would have a metrics field populated with the selected metrics.

For a list of queryable metrics, consult the Metrics documentation .

Query for segments

Alongside selected attributes for a given resource, you can also query for related segments:

  SELECT 
  
 campaign 
 . 
 id 
 , 
  
 campaign 
 . 
 name 
 , 
  
 campaign 
 . 
 status 
 , 
  
 metrics 
 . 
 impressions 
 , 
  
 segments 
 . 
 date 
 , 
 FROM 
  
 campaign 
 WHERE 
  
 campaign 
 . 
 status 
  
 = 
  
 'PAUSED' 
  
 AND 
  
 metrics 
 . 
 impressions 
 > 
 1000 
  
 AND 
  
 segments 
 . 
 date 
  
 during 
  
 LAST_30_DAYS 
 ORDER 
  
 BY 
  
 campaign 
 . 
 id 
 

Similar to querying for metrics, this query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions. However, this query segments the data by date. This leads to each resulting GoogleAdsRow representing a tuple of a campaign and the date Segment . Segmenting splits the selected metrics, grouping by each segment in the SELECT clause.

For a list of queryable segments, consult the Segments documentation .

Query for attributes of a related resource

In a query for a given resource, you may be able to join against other related resources if available. These related resources are known as "attributed resources". You can join against attributed resources implicitly by selecting an attribute in your query.

  SELECT 
  
 campaign 
 . 
 id 
 , 
  
 campaign 
 . 
 name 
 , 
  
 campaign 
 . 
 status 
 , 
  
 bidding_strategy 
 . 
 name 
 FROM 
  
 campaign 
 ORDER 
  
 BY 
  
 campaign 
 . 
 id 
 

This query not only selects campaign attributes, but also pulls in related attributes from each campaign selected. Each resulting GoogleAdsRow represents a campaign object populated with the selected campaign attributes, as well as the selected bidding strategy attribute bidding_strategy.name .

To find out what attributed resources are available for campaign queries, consult the Campaign reference documentation .

Mutate based on query results

When querying for a given resource, you can immediately take those returned results as objects, modify them, and send them back to the mutate method in that resource's service. Here is a sample workflow: 1. Execute a query for all campaigns that are currently PAUSED and have impressions greater than 1000. 1. Get the Campaign object from the campaign field of each GoogleAdsRow in the response. 1. Change the status of each campaign from PAUSED to ENABLED . 1. Call CampaignService.MutateCampaigns with the modified campaigns to update them.

Field metadata

Queries sent to GoogleAdsFieldService are meant for retrieving field metadata. This information can be used to understand how the fields can be used together in a query. Since data is available from the API and it provides the necessary metadata needed to validate or build a query, this allows for developers to do so programmatically. Here's a typical query for metadata:

  SELECT 
  
 name 
 , 
  
 category 
 , 
  
 selectable 
 , 
  
 filterable 
 , 
  
 sortable 
 , 
  
 selectable_with 
 , 
  
 data_type 
 , 
  
 is_repeated 
 WHERE 
  
 name 
  
 = 
  
 "<INSERT_RESOURCE_OR_FIELD>" 
 

You can replace <INSERT_RESOURCE_OR_FIELD> in this query with either a resource (such as customer or campaign ) or field (such as campaign.id , metrics.impressions , or ad_group.id ).

For a list of queryable fields, consult the GoogleAdsField documentation .

Code examples

The client libraries have examples of using the Google Ads Query Language in GoogleAdsService . The basic operationsfolder has examples such as GetCampaigns , GetKeywords , and SearchForGoogleAdsFields .