Requests for resource fields, segment fields and metric fields can be made via
using a query. To construct a query in Google Ads Query Language, you will need to build it using
the language grammar.
A query is made up of a number of clauses:
Clauses use field names, resource names, operators, conditions, and orderings to help you select the correct data. Once combined into a single query, a request can be made using Google Ads API. Let's look at how each clause can be used.
SELECT clause specifies a set of fields to fetch in the request.
SELECT takes a comma-separated list of resource fields, segment fields
and metrics, returning the values in the response.
SELECT clause is required in a query.
To get the ID and name of a campaign you can use the following query:
SELECT campaign.id, campaign.name FROM campaign
You can select certain fields without explicitly defining the resource in the
FROM clause. In this example you can request the campaign ID from ad groups:
SELECT campaign.id FROM ad_group
It is possible to request different field types in a single request. In this example we have:
SELECT campaign.id, campaign.name, ad_group.id, device, metrics.impressions, metrics.clicks FROM ad_group
FROM clause specifies the main resource that will be used to select
fields. The resource is used by the service to join with other resources and
segment data as required. Only a single resource can be specified in the
FROM clause is required in a query, however it should not
be specified when using
resource_name field of the main resource is always returned.
In the following example,
ad_group.resource_name will be included in the
response despite not being explicitly selected in the query:
SELECT ad_group.id FROM ad_group
The same is true for other resources when at least one field is selected.
campaign.resource_name will be included in the
response for the following query:
SELECT campaign.id, ad_group.id FROM ad_group
WHERE clause specifies conditions to apply when filtering data for the
request. When using the
WHERE clause, one or more conditions can be specified
AND to separate them. Each condition should follow the pattern
field_name Operator value.
WHERE clause is optional in a query.
The following is an example of using
WHERE to return metrics from a given time
SELECT campaign.id, campaign.name, metrics.impressions FROM campaign WHERE date DURING LAST_30_DAYS
You can combine multiple conditions to filter the data. This example will request the number of clicks for all campaigns with impressions on mobile in the last 30 days.
SELECT campaign.id, campaign.name, device, metrics.clicks FROM campaign WHERE metrics.impressions > 0 AND device = MOBILE AND date DURING LAST_30_DAYS
For a complete list of operators, consult the language grammar.
ORDER BY clause specifies the order in which the results should be
This allows you to arrange the data in ascending or descending order based on a
field name. Each ordering should be specified as a
field_name followed by
DESC. If neither of
DESC is specified, the order will
ORDER BY clause is optional in a query.
The following query will order the returned campaigns by number of clicks from highest to lowest:
SELECT campaign.name, metrics.clicks FROM campaign ORDER BY metrics.clicks DESC
You can specify multiple fields in the
ORDER BY clause using a comma-separated
The ordering will occur in the same sequence as specified in the query.
For example, in this query selecting ad group data, the results will be sorted
in ascending order by campaign name, then in descending order by number of
impressions, then in descending order by number of clicks.
SELECT campaign.name, ad_group.name, metrics.impressions, metrics.clicks FROM ad_group ORDER BY campaign.name, metrics.impressions DESC, metrics.clicks DESC
LIMIT clause allows you specify the number of results to be returned.
This is useful if you are only interested in a summary.
LIMIT can be used to restrict the total number of results for the
SELECT campaign.name, ad_group.name, device, metrics.impressions FROM ad_group ORDER BY metrics.impressions DESC LIMIT 50
In addition to the examples for each clause, Google Ads Query Language has the following behaviors:
It's not required for the main resource field to be in the
SELECTclause for a query. For example, you might want to only use one or more main resource fields to filter data:
SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
Metrics can be selected alone for a given resource. No other fields from the resource are required for a valid query:
SELECT metrics.impressions, metrics.clicks, metrics.costMicros FROM campaign
Segmentation fields can be selected without resource fields or metrics being requested:
SELECT device FROM campaign
campaign.resource_name, for example) can be used to filter or order data:
SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'