What is GAQL (Google Ads Query Language)?

An introduction to GAQL: the structure of a query, resources, fields and the rules that trip people up.

GAQL — Google Ads Query Language — is how you ask Google Ads for data. It looks like SQL, and it is what Google Ads scripts and the Google Ads API both use for reporting.

The shape of a query

SELECT campaign.name, metrics.clicks, metrics.cost_micros
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.clicks DESC
LIMIT 20

SELECT — the fields you want back.
FROM — one resource: campaign, ad_group, keyword_view, search_term_view, shopping_performance_view and many more.
WHERE — filters, combined with AND.
ORDER BY and LIMIT — sorting and the number of rows.

Three kinds of field

Attributes describe the thing itself: campaign.name, ad_group.status.
Metrics are numbers: metrics.impressions, metrics.conversions.
Segments split the numbers: segments.date, segments.device.

Adding a segment to SELECT multiplies the rows: one per campaign becomes one per campaign per day.

Rules that trip people up

One resource per query. There are no joins. Related resources are available through fields — from ad_group you can select campaign.name.
Not every field goes with every resource. Each resource has its own list of compatible fields.
No `OR`. Use IN (...) or run separate queries.
Cost is in micros. Divide metrics.cost_micros by 1,000,000.
Dates need a filter. If you select or segment by date, filter on segments.date.

Trying it out

GAQL Lab lets you write queries with autocomplete, validates them before they run, and shows results from any connected account. The Builder tab assembles a query from a form if you do not know the field names yet.

app.chiliad.io/gaql

GAQL Lab

EditorBuilder

1GrowthLab Store 234-567-8901 ▾

SELECT campaign.name, metrics.clicks, metrics.cost_micros
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.cost_micros DESC

Valid query

Examples:Campaign PerformanceKeywords + Quality ScoreSearch Terms2

Run Query3AdsApp.search()CSV5⌘↵ run

Results 4

3 rows · 0.8s

Copy CSV

#	Campaign Name	Clicks	Cost
1	Brand — Search	1,204	$312.40
2	Shopping — Core	986	$281.75
3	PMax — Prospecting	540	$198.10

1
Pick the account to query.
2
Start from an example and adapt it.
3
Run Query, or press Cmd+Enter. The validator flags unknown fields and syntax errors before you run.
4
Results with readable column names. Cost values in micros are converted for you.
5
Copy the query as an AdsApp.search() snippet for a script, or download the rows as CSV.

The shape of a query

SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 20

SELECT — the fields you want back.

FROM — one resource: campaign, ad_group, keyword_view, search_term_view, shopping_performance_view and many more.

WHERE — filters, combined with AND.

ORDER BY and LIMIT — sorting and the number of rows.

Rules that trip people up

One resource per query. There are no joins. Related resources are available through fields — from ad_group you can select campaign.name.

Not every field goes with every resource. Each resource has its own list of compatible fields.

No `OR`. Use IN (...) or run separate queries.

Cost is in micros. Divide metrics.cost_micros by 1,000,000.

Dates need a filter. If you select or segment by date, filter on segments.date.

Campaign Name

Clicks

Cost

Brand — Search

1,204

$312.40

Shopping — Core

986

$281.75

PMax — Prospecting

540

$198.10