Google Ads Query Language

  • The Google Ads Query Language allows querying the Google Ads API for resources, their attributes, segments, metrics, and metadata using GoogleAdsService and GoogleAdsFieldService.

  • Queries using GoogleAdsService return a list of GoogleAdsRow instances, each representing a resource and including requested attributes, metrics, or segmented data.

  • Queries using GoogleAdsFieldService return a list of GoogleAdsField instances providing metadata about available fields and resources.

  • You can query for resource attributes, metrics, segments, and attributes of related resources by selecting them in the query.

  • Query results can be used to mutate resources by retrieving objects from GoogleAdsRow, modifying them, and sending them to the resource's mutate method.

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.

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 operations folder has examples such as GetCampaigns, GetKeywords, and SearchForGoogleAdsFields.

Next
Query grammar