/gaql-reference

name: gaql-reference
description: Google Ads Query Language (GAQL) Reference — complete syntax, resource types, fields, operators, date macros, and ready-to-use query patterns
version: "1.0.0"
author: Cogny AI
platforms: []
user-invocable: true
argument-hint: "<query or topic>"
allowed-tools:
  - WebSearch
  - Read
  - Write
  - Bash
  # Google Ads tools (when connected via Cogny MCP)
  - mcp__cogny__google_ads__tool_execute_gaql
  - mcp__cogny__google_ads__tool_get_gaql_doc
  - mcp__cogny__google_ads__tool_get_reporting_view_doc
  - mcp__cogny__google_ads__tool_list_accessible_accounts

Google Ads Query Language (GAQL) Reference

Complete reference for GAQL syntax, resource types, fields, operators, date macros, and common query patterns for Google Ads reporting and optimization.

Full docs: https://cogny.com/docs/gaql-reference

Usage

/gaql-reference                           # Show full syntax overview
/gaql-reference search terms              # Search terms report pattern
/gaql-reference quality score             # Quality Score analysis query
/gaql-reference impression share          # Budget & impression share query
/gaql-reference geographic                # Geographic performance query
/gaql-reference change history            # Change history audit query

Instructions

You are a Google Ads Query Language (GAQL) expert. Use this reference to help users write correct GAQL queries, understand resource types, choose the right fields, and avoid common pitfalls.

When the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use GAQL examples.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of the GAQL syntax and available resources.

When the user has Cogny MCP tools available, prefer using `mcp__cogny__google_ads__tool_execute_gaql` to run queries directly and `mcp__cogny__google_ads__tool_get_gaql_doc` or `mcp__cogny__google_ads__tool_get_reporting_view_doc` for API documentation lookups.

---

Syntax

Formal Grammar

query         = SELECT field_list FROM resource_name
                [ WHERE condition_list ]
                [ ORDER BY field_name [ ASC | DESC ] ]
                [ LIMIT positive_integer ]
                [ PARAMETERS param_list ]

field_list    = field_name { , field_name }
condition_list = condition { AND condition }
condition     = field_name operator value
param_list    = param_name = param_value { , param_name = param_value }

Clauses

| Clause | Required | Description | |--------|----------|-------------| | `SELECT` | Yes | Fields to return (resource fields, metrics, segments) | | `FROM` | Yes | Single resource type to query | | `WHERE` | No | Filter conditions joined by `AND` (no `OR` support) | | `ORDER BY` | No | Sort by one field, `ASC` or `DESC` | | `LIMIT` | No | Maximum number of rows to return | | `PARAMETERS` | No | Query-level parameters (e.g., `include_drafts = true`) |

Example

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

Resource Types (FROM Clause)

Campaign Management

| Resource | Description | |----------|-------------| | `campaign` | Campaign settings, status, bidding, budget | | `campaign_budget` | Shared and campaign-level budgets | | `campaign_criterion` | Campaign-level targeting criteria | | `campaign_bid_modifier` | Bid adjustments at campaign level | | `bidding_strategy` | Portfolio bidding strategies |

Ad Groups & Ads

| Resource | Description | |----------|-------------| | `ad_group` | Ad group settings, status, targeting | | `ad_group_ad` | Ads within ad groups (RSA, ETA, etc.) | | `ad_group_ad_asset_view` | Asset-level performance for responsive ads | | `ad_group_criterion` | Keywords, audiences, and other criteria | | `ad_group_bid_modifier` | Bid adjustments at ad group level |

Performance Views

| Resource | Description | |----------|-------------| | `keyword_view` | Keyword-level performance metrics | | `search_term_view` | Actual search queries that triggered ads | | `landing_page_view` | Landing page performance | | `geographic_view` | Performance by geographic location | | `location_view` | Performance by targeted/excluded location | | `age_range_view` | Performance by age range demographic | | `gender_view` | Performance by gender demographic | | `user_location_view` | Performance by user's physical location | | `display_keyword_view` | Display network keyword performance | | `topic_view` | Display/video topic targeting performance | | `managed_placement_view` | Managed placement performance |

Conversion & Attribution

| Resource | Description | |----------|-------------| | `conversion_action` | Conversion action configuration | | `customer_conversion_goal` | Conversion goals and optimization settings |

Account & Extensions

| Resource | Description | |----------|-------------| | `customer` | Account-level settings | | `asset` | Account assets (sitelinks, callouts, images) | | `asset_group` | Performance Max asset groups | | `asset_group_asset` | Assets within asset groups |

Change History

| Resource | Description | |----------|-------------| | `change_status` | Recent changes to account entities | | `change_event` | Detailed change history with old/new values |

Common Fields

Campaign Fields

| Field | Type | Description | |-------|------|-------------| | `campaign.id` | INT64 | Unique campaign ID | | `campaign.name` | STRING | Campaign name | | `campaign.status` | ENUM | `ENABLED`, `PAUSED`, `REMOVED` | | `campaign.advertising_channel_type` | ENUM | `SEARCH`, `DISPLAY`, `SHOPPING`, `VIDEO`, `PERFORMANCE_MAX` | | `campaign.bidding_strategy_type` | ENUM | `TARGET_CPA`, `TARGET_ROAS`, `MAXIMIZE_CONVERSIONS`, `MANUAL_CPC`, etc. | | `campaign.cam