Queries for resource, segment, and metric fields can be sent toGoogleAdsServiceSearch orSearchStreammethods. To construct a query in Google Ads Query Language, you will need to build it using thelanguage grammar. A query is made up of a number ofclauses:

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

Clauses usefield names,resource names,operators,conditions, andorderings to help you select the correct data. When combined into a singlequery, a request can be made using Google Ads API.

Clauses

ondemand_videoVideo: GAQL Field Compatibility

SELECT

TheSELECT 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. TheSELECT clause isrequired in a query.

The sample query below shows an example of selecting attributes for a givenresource:

SELECTcampaign.id,campaign.nameFROMcampaign

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

SELECTcampaign.id,campaign.name,bidding_strategy.id,bidding_strategy.name,segments.device,segments.date,metrics.impressions,metrics.clicksFROMcampaignWHEREsegments.dateDURINGLAST_30_DAYS

• Resource fields

  • campaign.id
  • campaign.name

• Resource fields

  • bidding_strategy.id
  • bidding_strategy.name

• Segment fields

  • segments.device
  • segments.date

• Metrics

  • metrics.impressions
  • metrics.clicks

Some fields may not be allowed in theSELECT clause, due to the followingrestrictions:

• Querying fields that are not selectable. These fields will have theirSelectable metadata attribute marked asfalse.
• Selecting attributes of repeated fields. These fields will have theirisRepeated metadata attribute marked astrue.
• Selecting fields that are not available for the given resource in theFROMclause. Attributes of some resources cannot be selected together, also only asubset of all metrics and segments will be available for the resource in theFROM clause.
• Selecting segments or metrics that are not compatible with each other. Formore information on this, see thesegmentation section.

Information related to the above conditions can be found in our reference docsor fromGoogleAdsFieldService.

FROM

TheFROM clause specifies the main resource that will be returned. Theresource in theFROM clause defines what fields can be used all of the otherclauses for the given query. Only a single resource can be specified in theFROM clause. TheFROM clause isrequired in a query to theGoogleAdsServiceSearch orSearchStreammethods. However, theFROM clause shouldnot be specified when usingGoogleAdsFieldService.

While only one resource can exist in theFROM clause for a given query, fieldsfrom Attributed Resources may be available as well. These resources areimplicitly joined with the resource in theFROM clause, so you only need toadd their attributes to theSELECT clause to return their values. Not allresources have Attributed Resources. In the following example you can requestboth the ad group ID and the campaign ID from ad groups:

SELECTcampaign.id,ad_group.idFROMad_group

Theresource_name field of the main resource is always returned.In the following example,ad_group.resource_name will be included in theresponse despite not being explicitly selected in the query:

SELECTad_group.idFROMad_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 thefollowing query:

SELECTcampaign.id,ad_group.idFROMad_group

SELECTcampaign.id,campaign.name,metrics.impressionsFROMcampaignWHEREsegments.dateDURINGLAST_30_DAYS

SELECTcampaign.id,campaign.name,segments.device,metrics.clicksFROMcampaignWHEREmetrics.impressions >0ANDsegments.device=MOBILEANDsegments.dateDURINGLAST_30_DAYS

SELECTcampaign.id,campaign.name,segments.date,metrics.clicksFROMcampaignWHEREsegments.dateDURINGLAST_30_DAYS

When filtering, the case-sensitivity of your operator is important to keep inmind. SeeCase sensitivity for more details.

For a complete list of operators, consult thelanguage grammar.

ORDER BY

TheORDER BY clause specifies the order in which the results are to bereturned. This lets you arrange the data in ascending or descending orderbased on a field name. Each ordering is specified as afield_name followed byASC orDESC. If neitherASC norDESC is specified, the order defaultstoASC. TheORDER BY clause isoptional in a query.

The following query orders the returned campaigns by the number of clicks fromhighest to lowest:

SELECTcampaign.name,metrics.clicksFROMcampaignORDERBYmetrics.clicksDESC

You can specify multiple fields in theORDER BY clause using a comma-separatedlist. 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 sortedin ascending order by campaign name, then in descending order by number ofimpressions, then in descending order by number of clicks:

SELECTcampaign.name,ad_group.name,metrics.impressions,metrics.clicksFROMad_groupORDERBYcampaign.name,metrics.impressionsDESC,metrics.clicksDESC

LIMIT

TheLIMIT clause lets you 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 thefollowing query:

SELECTcampaign.name,ad_group.name,segments.device,metrics.impressionsFROMad_groupORDERBYmetrics.impressionsDESCLIMIT50

PARAMETERS

ThePARAMETERS 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

Setinclude_drafts totrue to allow draft entities to be returned. Defaults tofalse.

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

SELECTcampaign.nameFROMcampaignPARAMETERSinclude_drafts=true

omit_unselected_resource_names

Setomit_unselected_resource_names totrue to prevent the resource name ofeach resource type in the response from being returned unless explicitlyrequested in theSELECT clause. Defaults tofalse.

SELECTcampaign.name,customer.idFROMcampaign

SELECTcampaign.name,customer.idFROMcampaignPARAMETERSomit_unselected_resource_names=true

SELECTcampaign.name,campaign.resource_nameFROMcampaignPARAMETERSomit_unselected_resource_names=true