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