Query structure

Page Summary

• Queries for resource, segment, and metric fields can be sent to GoogleAdsService Search or SearchStream methods.

• A Google Ads Query Language query is made up of clauses: SELECT, FROM, WHERE, ORDER BY, LIMIT, and PARAMETERS.

• The SELECT and FROM clauses are required in a query when using GoogleAdsService, while the other clauses are optional.

• The GoogleAdsFieldService provides metadata about resource fields, segment fields, metrics, and their relationships for Google Ads Query Language clients.

Tip: Use the Interactive Query Builder to build and validate your Google Ads Query Language queries.

Queries for resource, segment, and metric fields can be sent to the GoogleAdsService Search or SearchStream method. To construct a query in Google Ads Query Language, build it using the language grammar. For a general overview of Google Ads Query Language, see the Google Ads Query Language overview. 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. When combined into a single query, you can send the request to Google Ads API.

Key Point: The GoogleAdsFieldService provides a catalog for Google Ads Query Language clients with metadata about all resource fields, segment fields, and metrics, their relationships to each other, and their availability in each clause. Because the set of queryable resources, fields, segments, and metrics varies across major API versions, query GoogleAdsFieldService at the endpoint for the API version you are targeting. For more details, refer to the documentation for GoogleAdsField and Version-specific differences.

Clauses

The following sections describe the purpose and syntax of each Google Ads Query Language clause.

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.

The following sample query shows an example of selecting attributes for a given resource:

SELECT
  campaign.id,
  campaign.name
FROM campaign

You can request different field types in a single request, for example:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Main resource fields
  • campaign.id
  • campaign.name
• Attributed resource fields
  • bidding_strategy.id
  • bidding_strategy.name
• Segment fields
  • segments.device
  • segments.date
• Metrics
  • metrics.impressions
  • metrics.clicks

Note: Some fields cannot be selected in the SELECT clause because of the following restrictions:

• Querying fields that are not selectable. These fields have their selectable metadata attribute marked as false.
• Selecting attributes of repeated fields. These fields have their is_repeated metadata attribute marked as true.
• Selecting fields that are not available for the given resource in the FROM clause. Attributes of some resources cannot be selected together, and only a subset of all metrics and segments is available for the resource in the FROM clause.
• Selecting segments or metrics that are not compatible with each other. For more information, see Segmentation.

Information related to the preceding conditions can be found in our reference documentation or from GoogleAdsFieldService.

FROM

The FROM clause specifies the main resource to return. The resource in the FROM clause defines what fields can be used in all of the other clauses for the given query. Only a single resource can be specified in the FROM clause. The FROM clause is required in a query to the GoogleAdsService Search or SearchStream method. However, the FROM clause should not be specified when using GoogleAdsFieldService.

While only one resource can exist in the FROM clause for a given query, fields from attributed resources may be available as well. These resources are implicitly joined with the resource in the FROM clause, so you only need to add their attributes to the SELECT clause to return their values. Not all resources have attributed resources. In the following 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 is included in the response despite not being explicitly selected in the query:

SELECT ad_group.id
FROM ad_group

The same is true for attributed resources when at least one field is selected. For example, campaign.resource_name is included in the response for the following query:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Key Point: If the resource in the FROM clause lists another resource as a segment, then selecting any attributes of that resource acts as a segment.

WHERE

The WHERE clause specifies conditions to apply when filtering data for the request. When using the WHERE clause, specify one or more conditions separated by AND. Conditions typically follow the pattern field_name Operator value (or use BETWEEN value AND value, IS NULL, or IS NOT NULL). The WHERE clause is optional in a query.

The following example uses 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 requests 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

Segments in the WHERE clause must also be in the SELECT clause, except for the following date segments, referred to as core date segments:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

In the following query, segments.date is selected. Because this segment is a core date segment, you must provide a finite date range in the WHERE clause composed of core date segments:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

All segments that meet the preceding condition are segments.date, segments.week, segments.month, segments.quarter, and segments.year. If any of these segments are selected, at least one of them must be used in the WHERE clause.

For more details on date filtering, see Date ranges.

Key Point: The separator AND can only be used between operator conditions (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE'), and not within a single operator condition (WHERE segments.device != 'DESKTOP' AND 'MOBILE').

When filtering, keep the case sensitivity of your operator in mind. For more information, see Case sensitivity.

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

ORDER BY

The ORDER BY clause specifies the order in which results are returned. This lets you 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 the 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 occurs in the same sequence as specified in the query. For example, in this query selecting ad group data, the results are 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 lets you specify the number of results to return. This is useful if you only need a subset of results.

For example, LIMIT can 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 lets you truncate the results. To retrieve large result sets without truncating, use GoogleAdsService.SearchStream to stream rows or paginate with GoogleAdsService.Search.

PARAMETERS

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

The following meta parameters are supported:

include_drafts

Set include_drafts to true to return draft entities. Defaults to false.

For example, the following query fetches draft campaigns along with regular campaigns:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Set omit_unselected_resource_names to true to omit the resource name of each resource type in the response unless explicitly requested in the SELECT clause. Defaults to false.

Note: If you plan to use any of the returned objects for update or remove operations, we recommend setting this option to false because resources without resource names cannot be used in mutate operations. If you set this option to true, make sure you explicitly request the resource names of both the primary resource and any attributed resources you fetch using the query.

Query	Returned resources
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name omit_unselected_resource_names defaults to false, so all resource_name fields are returned.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	None omit_unselected_resource_names is specified as true, and neither campaign.resource_name nor customer.resource_name is part of the SELECT clause.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	campaign.resource_name omit_unselected_resource_names is specified as true, and campaign.resource_name is requested as part of the SELECT clause.

Additional language rules

In addition to the examples for each clause, Google Ads Query Language supports the following behaviors:

• The main resource field is not required in the SELECT clause for a query. For example, you can use one or more main resource fields to filter data without selecting them:

  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.cost_micros
  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'