Skip to content
GetProfit
Log in

← All terms

GAQL (Google Ads Query Language)

GAQL is the query language of the Google Ads API: each SQL-like query names one resource and the fields, segments and metrics to return for it.

How it works

A query needs SELECT and FROM; WHERE, ORDER BY, LIMIT and PARAMETERS are optional. FROM names a single resource. There is no JOIN: to get fields of a related resource, such as an ad group’s campaign, you add them to SELECT.

There is no GROUP BY either: each segment in SELECT, such as segments.date, splits the metrics into one row per value. If you select a date segment, WHERE must set a finite date range. WHERE combines conditions only with AND; instead of OR, Google suggests IN or REGEXP_MATCH.

For product-level reporting, shopping_performance_view holds the metrics of products that served ads, shopping_product the current state of every product, and asset_group_product_group_view the listing groups of Performance Max. The same queries run in Google Ads scripts and in Google’s MCP server. For working queries and the data traps to avoid, see Google Ads API for product reporting.

Example

Example store, not client data.

SELECT segments.product_item_id, metrics.impressions, metrics.cost_micros
FROM shopping_performance_view
WHERE segments.date DURING LAST_30_DAYS

The tableware shop gets 1,200 rows, one per product with impressions; the other 1,800 of its 3,000 products get no row. Cost comes in micros, millionths of a currency unit: a plate with cost_micros 25,000,000 cost 25.

Not to be confused with

  • Google Ads API — the interface GAQL runs through. GAQL only reads data; changes go out as separate mutate requests.
  • BigQuery Data Transfer Service — loads Google Ads reports into BigQuery tables at most once a day. A GAQL query can define a custom report, but you query the stored tables in BigQuery.

Right and wrong readings

  • Wrong: “WHERE segments.product_item_id = 'PLT-0457' returns nothing, so the plate never served.” Right: in our client accounts, product reports return the item ID in lowercase, and = is case sensitive. Filter by 'plt-0457', or use LIKE, which ignores case.
  • Wrong: “The date-segmented report has no row for 14 March, so data failed to load.” Right: once a report is segmented, rows whose selected metrics are all zero are left out.

Sources