The Google Ads Query Language provides the flexibility to query the Google Ads API for:
Any resource or stat in
GoogleAdsService.Search. You would use Google Ads Query Language for these purposes:
- To query multiple resources at a time because each of the services returns
only one resource at a time using the
- To query stats such as impressions and clicks. For a full list of metrics,
- To query multiple resources at a time because each of the services returns only one resource at a time using the
Query for metadata about the fields and resources available in
GoogleAdsFieldService. You would use this query language for the purpose of getting a catalog of what fields are available to query in the Google Ads API along with specifics about compatibility and types.
The result of
GoogleAdsService queries is a list of
GoogleAdsRow contains the resource. If metrics were requested,
then it also includes metrics.
The result of
GoogleAdsFieldService queries is a list of
GoogleAdsField contains details about the field that you requested.
When querying for stats, you can also have the details of the associated
resources returned at the same time. You can then immediately take those
resources, modify them, and then send them back to the
Mutate methods of
their services. This means that the following example workflow is possible:
- Query all the campaigns that are currently
PAUSEDand have impressions greater than 1000.
- Process each
GoogleAdsRowreturned in the list, and retrieve the campaigns that are in each
- Change the status of each campaign from
CampaignService.MutateCampaignswith the modified campaigns to update them.
There are times when you may not care about the stats. Here's a query for campaigns showing how to get the campaign ID, name, and status, while ordering by campaign ID.
SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id
To find out what other fields are available to query for campaign, consult
GoogleAdsRow has a
campaign populated with the selected fields.
When querying for stats, you can query for the resource and stats at the same
time. Here's a query for campaigns showing how to get the campaign ID, name,
status, and impressions. The query filters for only the campaigns that have
a status of
PAUSED and have had greater than 1000 impressions while ordering
by campaign ID.
SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'PAUSED' AND metrics.impressions > 1000 ORDER BY campaign.id
GoogleAdsRow has a
campaign populated with the selected fields,
metrics populated with the selected metrics.
Fields metadata query
Queries can be used with the
GoogleAdsFieldService to view field metadata.
Here's a query for getting the field metadata for
campaign.id. You can
campaign.id in this query with either a resource (such as
campaign) or a field (such as
note that there's no
FROM clause in this query.
SELECT name, category, selectable, filterable, sortable, selectable_with, data_type, is_repeated WHERE name = campaign.id
To find out what other fields are available to query for field metadata, consult
The client libraries have examples of using the
Google Ads Query Language in the
GoogleAdsService. The basic operations folder has
examples such as
The reporting folder has the
For more information on the Google Ads Query Language, continue reading: