Query Structure

Queries for resource, segment, and metric fields can be sent to GoogleAdsService Search or SearchStream methods. 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:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

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.

Key Point: The GoogleAdsFieldService provides a catalog for Google Ads Query Language clients with metadata about all of the resource fields, segment fields, and metrics, as well as their relationships to each other and availability in each clause as defined below. For more details, refer to the documentation for GoogleAdsField.

Clauses

SELECT

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

It is possible to request different field types in a single request, for example:

• Resource fields

  • campaign.id
  • campaign.name
  • ad_group.name

• Segment fields

  • segments.device

• Metrics

  • metrics.impressions
  • metrics.clicks

SELECT
  ad_group.name,
  ad_group.id,
  segments.device,
  metrics.impressions,
  metrics.clicks
FROM ad_group

The SELECT clause is not allowed in the following cases:

• Querying fields that have their Selectable metadata attribute marked as false.

• Selecting attributes of repeated fields. Repeated fields will have the isRepeated property in their metadata marked as true. This information can be found in our docs or from GoogleAdsFieldService.

FROM

The 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. The FROM clause is required in a query, however it should not be specified when using GoogleAdsFieldService.

You can select fields from other resources without explicitly defining the resource in the FROM clause. These fields are implicitly joined with the resource in the FROM clause. If the resource in the FROM clause contains the joined resource in its segments attribute, the joined resource will act as a segment. If the joined resource is in the AttributedResources attribute, it can be selected without any impact on metrics. Not all resources have Attributed Resources. In this example you can request both the ad group ID and the campaign ID from ad groups:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

The 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. For example: campaign.resource_name will be included in the response for the following query:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

The WHERE clause specifies conditions to apply when filtering data for the request. When using the WHERE clause, one or more conditions can be specified using AND to separate them. Each condition should follow the pattern field_name Operator value. The WHERE clause is optional in a query.

The following is an example of using WHERE to return metrics from a given time period:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.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,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

Key Point: The condition separator AND is not an operator and cannot be used in a condition.

For a complete list of operators, consult the language grammar.

ORDER BY

The ORDER BY clause specifies the order in which the results are to be returned. This allows you to arrange the data in ascending or descending order based on a field name. Each ordering is specified as a field_name followed by ASC or DESC. If neither ASC nor DESC is specified, the order defaults to ASC. The ORDER BY clause is optional in a query.

The following query orders 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 list. 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

The LIMIT clause allows you to specify the number of results to be returned. This is useful if you're only interested in a summary.

For example, LIMIT can be used to restrict the total number of results for the following query:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Key Point: LIMIT allows you to truncate the results. Use the page_size field of the GoogleAdsService.Search to handle long lists of results.

PARAMETERS

The PARAMETERS clause allows you to specify meta parameters for the request. These parameters may impact what kinds of rows are returned.

Currently, only one meta parameter is supported:

• include_drafts: Set to true to allow draft entities to be returned. Defaults to false.

For example, PARAMETERS can be used to fetch draft campaigns along with regular campaigns:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Language rules

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 SELECT clause 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 exclusively selected for a given resource; no other fields from the resource are required in the query:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.costMicros
  FROM campaign
  

• Segmentation fields can be selected without any accompanying resource fields or metrics:

  SELECT segments.device FROM campaign
  

• The resource_name field (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'