GAQL (Google Ads Query Language)

GAQL (Google Ads Query Language) is a SQL-like query language used to retrieve campaign data from the Google Ads API. It allows developers to select specific resource fields and metrics, apply filters, and sort results using a structured syntax that replaces the older AWQL (AdWords Query Language).

Key Takeaways

• SQL-like syntax for querying Google Ads data through the API
• Supports resource fields, metrics, segments, filtering, ordering, and limiting
• Used with the GoogleAdsService.Search and SearchStream methods
• Replaced AWQL (AdWords Query Language) with the migration from AdWords API to Google Ads API
• Requires understanding of Google Ads resource relationships and metric compatibility

What Is GAQL

GAQL provides structured data access to the entire Google Ads object hierarchy. Instead of navigating the web interface or downloading CSV reports, developers write GAQL queries to retrieve exactly the data they need in a programmatic format.

GAQL Component	SQL Equivalent	Purpose
SELECT	SELECT	Choose fields and metrics to return
FROM	FROM	Specify the resource (table) to query
WHERE	WHERE	Filter results by conditions
ORDER BY	ORDER BY	Sort results
LIMIT	LIMIT	Restrict number of rows returned
PARAMETERS	N/A	Control behavior like include_drafts

How It Works

GAQL queries follow this structure:

SELECT field1, field2, metric1
FROM resource
WHERE condition1 AND condition2
ORDER BY metric1 DESC
LIMIT 100

Key concepts:

1. Resources — GAQL queries a specific resource type (campaign, ad_group, keyword_view, search_term_view, etc.). Each resource has its own available fields and compatible metrics.

2. Fields vs. Metrics — Resource fields are attributes (campaign.name, ad_group.status). Metrics are aggregated performance data (metrics.clicks, metrics.conversions). Segments add dimensional breakdowns (segments.device, segments.date).

3. Implicit joins — GAQL handles relationships automatically. Querying ad_group gives access to both ad group fields and parent campaign fields through attributed resources.

4. Metric compatibility — Not all metrics are available on all resources. The Google Ads API documentation specifies which metrics can be selected from each resource.

Common query patterns:

Use Case	Resource	Key Fields
Campaign performance	campaign	campaign.name, metrics.cost_micros, metrics.conversions
Keyword data	keyword_view	ad_group_criterion.keyword.text, metrics.clicks
Search terms	search_term_view	search_term_view.search_term, metrics.impressions
Ad performance	ad_group_ad	ad_group_ad.ad.responsive_search_ad.headlines
Change history	change_event	change_event.change_date_time, change_event.changed_fields

Practical Example

An analytics platform needs keyword performance data for the last 30 days:

SELECT
  campaign.name,
  ad_group.name,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC
LIMIT 500

This returns the top 500 active keywords by spend with full performance metrics. The cost_micros field returns cost in micros (millionths of the account currency), so $15.50 appears as 15500000.

Why It Matters

GAQL is the data access layer for every application built on the Google Ads API. Mastering it determines how efficiently you can retrieve data and how much API quota you consume. Well-written GAQL queries request only the fields needed, apply server-side filtering to reduce data transfer, and use appropriate date ranges to avoid pulling unnecessary historical data. Poorly constructed queries waste API rate limit quota, transfer excessive data, and slow down applications. For developers building Google Ads tools, GAQL proficiency is as important as the programming language itself.