Google Ads Query Language

Page Summary

• The Google Ads Query Language allows querying the Google Ads API for resources, their attributes, segments, metrics, and metadata using GoogleAdsService and GoogleAdsFieldService.

• Queries using GoogleAdsService return a list of GoogleAdsRow instances, each representing a resource and including requested attributes, metrics, or segmented data.

• Queries using GoogleAdsFieldService return a list of GoogleAdsField instances providing metadata about available fields and resources.

• You can query for resource attributes, metrics, segments, and attributes of related resources by selecting them in the query.

• Query results can be used to mutate resources by retrieving objects from GoogleAdsRow, modifying them, and sending them to the resource's mutate method.

Tip: Use the Interactive Query Builder to build and validate your GAQL queries.

Key terminology

Resource

An entity in Google Ads, such as campaign or ad_group.

Segment

A dimension used to group data, such as segments.date or segments.device. When segments are included in the SELECT clause with metrics, metrics are split by segment.

Metric

A measurement of performance, such as metrics.impressions or metrics.clicks.

Attributed Resource

A resource that is implicitly joined to the main resource in the FROM clause, allowing you to select its attributes along with main resource attributes.

Query for resource or metadata information

The Google Ads Query Language can query the Google Ads API for the following types of information:

• Resources and their related attributes, segments, and metrics using GoogleAdsService Search or SearchStream: The result from a GoogleAdsService query is a list of GoogleAdsRow instances, with each GoogleAdsRow representing a resource.

  If any attributes or metrics are requested, then the row also includes those fields. If any segments are requested, then the response also shows an additional row for each segment-resource tuple.

• Metadata about available fields and resources in GoogleAdsFieldService: This service provides a catalog of queryable fields with specifics about their compatibility and type.

  The result from a GoogleAdsFieldService query is a list of GoogleAdsField instances, with each GoogleAdsField containing details about the requested field.

For more details on query structure, see Query structure and Google Ads Query Language grammar.

Query for resource attributes

Here is an example of a basic query for attributes of the campaign resource that illustrates how to return the campaign ID, name, and status:

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

This query orders by campaign ID. Each resulting GoogleAdsRow represents a campaign object populated with the selected fields, including the campaign's resource_name.

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

Query for metrics

Alongside selected attributes for a given resource, you can also query for related metrics:

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

This query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions, while ordering by campaign ID. Each resulting GoogleAdsRow would have a metrics field populated with the selected metrics.

For a list of queryable metrics, consult the Metrics documentation.

Query for segments

Alongside selected attributes for a given resource, you can also query for related segments:

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

Similar to querying for metrics, this query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions. However, this query segments the data by date. This leads to each resulting GoogleAdsRow representing a tuple of a campaign and the date segment. Segmenting splits the selected metrics, grouping by each segment in the SELECT clause.

For a list of queryable segments, consult the Segments documentation.

Query for attributes of a related resource

In a query for a given resource, you may be able to join against other related resources if available. These related resources are known as "attributed resources". You can join against attributed resources implicitly by selecting an attribute in your query.

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

This query not only selects campaign attributes, but also pulls in related attributes from each campaign selected. Each resulting GoogleAdsRow represents a campaign object populated with the selected campaign attributes, as well as the selected bidding strategy attribute bidding_strategy.name.

To find out what attributed resources are available for campaign queries, consult the Campaign reference documentation.

Best practices

• Select only the fields you need to avoid long response times and timeouts.
• Use LIMIT during development and testing to avoid processing large result sets.
• Apply filters in the WHERE clause to minimize data transfer and response size.
• Use GoogleAdsFieldService to check field compatibility and data types before constructing complex queries.
• Be mindful that some fields, especially those involving large amounts of data or complex calculations, can increase query cost.

Mutate based on query results

When querying for a given resource, you can immediately take those returned results as objects, modify them, and send them back to the mutate method in that resource's service. Here is a sample workflow:

1. Execute a query for all PAUSED campaigns that have impressions greater than 1000.
2. Get the Campaign object from the campaign field of each GoogleAdsRow in the response.
3. Change the status of each campaign from PAUSED to ENABLED.
4. Call CampaignService.MutateCampaigns with the modified campaigns and a corresponding FieldMask to update them.

Note: When updating resources retrieved from a query, specify a FieldMask (or use your client library's built-in field mask utility) so that only the modified fields are updated, avoiding READ_ONLY_FIELD or IMMUTABLE_FIELD errors, or unintentionally overwriting other attributes.

Field metadata

Queries sent to GoogleAdsFieldService are meant for retrieving field metadata. This information can be used to understand how the fields can be used together in a query. Since data is available from the API and it provides the necessary metadata needed to validate or build a query, this allows for developers to do so programmatically. Here's a typical query for metadata:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

You can replace <INSERT_RESOURCE_OR_FIELD> in this query with either a resource (such as customer or campaign) or field (such as campaign.id, metrics.impressions, or ad_group.id).

Key Point: Note that there's no FROM clause in this query.

For a list of queryable fields, consult the GoogleAdsField documentation.

Version-specific differences

While Google Ads Query Language syntax, clauses, and operators are identical across all supported Google Ads API versions (v23, v24, and v25), the catalog of queryable resources, segments, metrics, and reporting behaviors differs by major version. Query GoogleAdsFieldService at the target API version endpoint to inspect the fields and compatibility rules for that version:

• Lifecycle goal resources: In v25 and later, all lifecycle goals (New Customer Acquisition, Customer Retention, and Loyalty Retention) are queried from the unified goal and campaign_goal_config resources, replacing customer_lifecycle_goal and campaign_lifecycle_goal (which were used for New Customer Acquisition goals in v24 and earlier, alongside goal and campaign_goal_config for Customer Retention goals).
• Final URL expansion asset view metrics: In v25 and later, querying final_url_expansion_asset_view returns all selectable metrics for the view. In v24 and earlier, responses include only metrics.conversions and metrics.conversions_value for Performance Max campaigns and metrics.impressions for Search campaigns.
• Shopping product reporting for App campaigns: In v24 and later, the shopping_product resource returns product rows for App campaigns in addition to Shopping, Performance Max, Demand Gen, and Video campaigns (in v23, App campaigns are excluded from shopping_product results).
• Version-specific resources, segments, and metrics:
  • v25 and later: Includes lift measurement resources (such as lift_measurement_config), segments such as segments.ad_sub_format_type and segments.loyalty_membership, and YouTube engagement metrics (metrics.youtube_likes, metrics.youtube_comments, and metrics.youtube_shares). Removes local_services_lead.contact_details.email (which is selectable in v24 and earlier).
  • v24 and later: Includes the cart_data_sales_view resource, segments.conversion_attribution_event_type on shopping_performance_view, segments.mobile_device_platform, and segments.ad_network_type on performance_max_placement_view. Removes campaign.video_brand_safety_suitability (replaced by customer.video_brand_safety_suitability), segments.ad_sub_network_type on campaign_budget, and segments.click_type on ad_group_asset, campaign_asset, and customer_asset (which are selectable only in v23).
• Granular date lookback error code: Queries that segment by segments.date, segments.week, or segments.hour (or filter on a sub-monthly date range) beyond the 37-month lookback window return DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED in v24 and later (or DateRangeError.UNKNOWN in v23). See Date ranges for details.

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