Google Ads Query Language

The Google Ads Query Language provides the flexibility to query the Google Ads API for:

• Any resource or stat in GoogleAdsService.Search. You would use Google Ads Query Language for these purposes:

  • To query multiple resources at a time because each of the services returns only one resource at a time using the Get method.
  • To query stats such as impressions and clicks. For a full list of metrics, consult Metrics.

• Query for metadata about the fields and resources available in GoogleAdsFieldService. You would use this query language for the purpose of getting a catalog of what fields are available to query in the Google Ads API along with specifics about compatibility and types.

The result of GoogleAdsService queries is a list of GoogleAdsRow instances. Each GoogleAdsRow contains the resource. If metrics were requested, then it would also includes metrics.

The result of GoogleAdsFieldService queries is a list of GoogleAdsField instances. Each GoogleAdsField contains details about the field that was requested.

Example

When querying for stats, you can also have the details of the associated resources returned at the same time. You can then immediately take those resources, modify them, and then send them back to the Mutate methods of their services. This means that the following example workflow is possible:

• Query all the campaigns that are currently PAUSED and have impressions greater than 1000.
• Process each GoogleAdsRow returned in the list, and retrieve the campaigns that are in each GoogleAdsRow.
• Change the status of each campaign from PAUSED to ENABLED.
• Call CampaignService.MutateCampaigns with the modified campaigns to update them.

Resources query

There are times when you may not care about the stats. Here's a query for campaigns showing how to get the campaign ID, name, and status, while ordering by campaign ID.

SELECT campaign.id, campaign.name, campaign.status
FROM campaign
ORDER BY campaign.id

To find out what other fields are available for campaign queries, consult Campaign.

Each GoogleAdsRow has a campaign populated with the selected fields.

Stats query

When querying for stats, you can query for the resource and stats at the same time. Here's a query for campaigns showing how to get the campaign ID, name, status, and impressions. The query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions while ordering by campaign ID.

SELECT campaign.id, campaign.name, campaign.status, metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED' AND metrics.impressions > 1000
ORDER BY campaign.id

To find out what other metrics are available, consult Metrics.

Each GoogleAdsRow has a metrics populated with the selected metrics.

Fields metadata query

Queries can be used with the GoogleAdsFieldService to view field metadata. Here's a query for getting the field metadata for campaign.id. You can replace campaign.id in this query with either a resource (such as customer, campaign) or a field (such as metrics.impressions or ad_group.id). Note that there's no FROM clause in this query.

SELECT name, category, selectable, filterable, sortable, selectable_with,
       data_type, is_repeated
WHERE name = campaign.id

To find out what other fields are available to query for field metadata, consult GoogleAdsField.

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 GetArtifactMetadata. The reporting folder has a GetKeywordStats example.