Google Ads Query Language

The Google Ads Query Language can query the Google Ads API for

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.

Querying for attributes of a resource

Below is a basic query for attributes of the campaign resource, illustrating how to return 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 would represent a campaign object populated with the selected fields (including that given campaign's resource_name).

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

Querying 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.

Querying 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. It's important to note that 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.

Mutating 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. Below is a sample workflow:

  1. Execute a query for all campaigns that are currently PAUSED and have impressions greater than 1000.
  2. Get the Campaign object from the campaign field of each GoogleAdsRow in the response.
  3. Change the status of each campaign from PAUSED to ENABLED.
  4. 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 GetArtifactMetadata. The reporting folder has a GetKeywordStats example.

Next
Query grammar