The Google Ads Query Language can query the Google Ads API for
- Resources and their related attributes, segments, and metrics using
GoogleAdsServiceSearch or SearchStream
- The result from a GoogleAdsService query is a list of
GoogleAdsRowinstances, with each
GoogleAdsRowrepresenting 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
This service provides a catalog of queryable fields with specifics about their compatibility and type.
The result from a
GoogleAdsFieldServicequery is a list of
GoogleAdsFieldinstances, with each
GoogleAdsFieldcontaining 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
campaign object populated with the selected fields (including that given
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
have had greater than 1000 impressions, while ordering by campaign ID. Each
GoogleAdsRow would have a
metrics field populated with the
For a list of queryable metrics, consult the
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
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
Querying 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
campaign object populated with the selected campaign attributes as well as
the selected bidding strategy attribute
To find out what attributed resources are available for campaign queries,
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:
- Execute a query for all campaigns that are currently
PAUSEDand have impressions greater than 1000.
- Get the
Campaignobject from the
campaignfield of each
GoogleAdsRowin the response.
- Change the status of each campaign from
CampaignService.MutateCampaignswith the modified campaigns to update them.
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
campaign) or field (such as
For a list of queryable fields, consult the
The client libraries have examples of using the
Google Ads Query Language in
GoogleAdsService. The basic operations folder has
examples such as
The reporting folder has a