mcpField
G
gaql-reference

gaql-reference

github.com/cognyai营销与增长11149 次安装2 周前更新
代码仓库

关于 gaql-reference

gaql-reference 是编写和理解 Google Ads Query Language 查询的参考技能，面向 Google Ads 分析师和广告运营人员。它说明语法、资源与字段，并提供报表和优化查询模式。

主要功能

  1. 01GAQL 语法与子句参考
  2. 02资源类型和字段说明
  3. 03筛选运算符与日期宏
  4. 04效果分析与审计查询模式
  5. 05常见查询问题提示

适用场景

  1. 01构建广告系列效果报表
  2. 02查询搜索词、关键词或地理表现
  3. 03分析质量得分与展示份额
  4. 04检查 Google Ads 转化操作或变更历史

MCP 相关

提供 Cogny MCP 工具时，该技能可指导直接执行 GAQL 查询，并查阅 Google Ads API 文档。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cognyai/claude-code-marketing-skills --skill gaql-reference

安装后在 Claude Code 中输入/gaql-reference确认已加载。

详细介绍

Google Ads Query Language（GAQL）参考

涵盖 GAQL 语法、资源类型、字段、运算符、日期宏，以及用于 Google Ads 报告和优化的常见查询模式的完整参考。

完整文档：https://cogny.com/docs/gaql-reference

用法

/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

说明

你是 Google Ads Query Language（GAQL）专家。请使用此参考帮助用户编写正确的 GAQL 查询、了解资源类型、选择合适的字段并避免常见问题。

用户提问时，请找到下方相关章节，并提供准确、可操作且可直接使用的 GAQL 示例。

如果用户将特定主题作为参数提供，请重点介绍该主题。否则，请概述 GAQL 语法和可用资源。

如果用户可以使用 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 查阅 API 文档。

语法

形式语法
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 }
子句
子句必需说明
SELECT是要返回的字段（资源字段、指标、细分）
FROM是要查询的单个资源类型
WHERE否使用 AND 连接的筛选条件（不支持 OR）
ORDER BY否按一个字段排序，使用 ASC 或 DESC
LIMIT否要返回的最大行数
PARAMETERS否查询级参数（例如，include_drafts = true）
示例
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

资源类型（FROM 子句）

广告系列管理
资源说明
campaign广告系列设置、状态、出价和预算
campaign_budget共享预算和广告系列级预算
campaign_criterion广告系列级定位条件
campaign_bid_modifier广告系列级出价调整
bidding_strategy组合出价策略
广告组和广告
资源说明
ad_group广告组设置、状态和定位
ad_group_ad广告组中的广告（RSA、ETA 等）
ad_group_ad_asset_view自适应广告的素材级效果
ad_group_criterion关键字、受众及其他条件
ad_group_bid_modifier广告组级出价调整
效果视图
资源说明
keyword_view关键字级效果指标
search_term_view触发广告的实际搜索查询
landing_page_view着陆页效果
geographic_view按地理位置划分的效果
location_view按定位位置或排除位置划分的效果
age_range_view按年龄段人口统计信息划分的效果
gender_view按性别人口统计信息划分的效果
user_location_view按用户实际位置划分的效果
display_keyword_view展示广告网络关键字效果
topic_view展示广告和视频主题定位效果
managed_placement_view托管版位效果
转化和归因
资源说明
conversion_action转化操作配置
customer_conversion_goal转化目标和优化设置
账号和附加信息
资源说明
customer账号级设置
asset账号素材（附加链接、宣传信息、图片）
asset_groupPerformance Max 素材组
asset_group_asset素材组中的素材
更改历史记录
资源说明
change_status账号实体的近期更改
change_event包含旧值和新值的详细更改历史记录

常见字段

广告系列字段
FieldTypeDescription
campaign.idINT64唯一广告系列 ID
campaign.nameSTRING广告系列名称
campaign.statusENUMENABLED、PAUSED、REMOVED
campaign.advertising_channel_typeENUMSEARCH、DISPLAY、SHOPPING、VIDEO、PERFORMANCE_MAX
campaign.bidding_strategy_typeENUMTARGET_CPA、TARGET_ROAS、MAXIMIZE_CONVERSIONS、MANUAL_CPC 等
campaign.campaign_budgetRESOURCE预算资源名称
campaign.start_dateDATE广告系列开始日期
campaign.end_dateDATE广告系列结束日期
campaign.serving_statusENUMSERVING、NONE、ENDED、PENDING、SUSPENDED
campaign.target_cpa.target_cpa_microsINT64以微单位表示的目标 CPA
campaign.target_roas.target_roasDOUBLE以比率表示的目标 ROAS
广告组字段
FieldTypeDescription
ad_group.idINT64唯一广告组 ID
ad_group.nameSTRING广告组名称
ad_group.statusENUMENABLED、PAUSED、REMOVED
ad_group.typeENUMSEARCH_STANDARD、DISPLAY_STANDARD、SHOPPING_PRODUCT_ADS 等
ad_group.cpc_bid_microsINT64以微单位表示的默认 CPC 出价
ad_group.target_cpa_microsINT64广告组级别的目标 CPA
广告字段
FieldTypeDescription
ad_group_ad.ad.idINT64唯一广告 ID
ad_group_ad.ad.typeENUMRESPONSIVE_SEARCH_AD、EXPANDED_TEXT_AD 等
ad_group_ad.ad.final_urlsSTRING (repeated)落地页 URL
ad_group_ad.statusENUMENABLED、PAUSED、REMOVED
ad_group_ad.ad.responsive_search_ad.headlinesMESSAGE (repeated)RSA 标题素材
ad_group_ad.ad.responsive_search_ad.descriptionsMESSAGE (repeated)RSA 描述素材
ad_group_ad.policy_summary.approval_statusENUMAPPROVED、DISAPPROVED 等
关键字和条件字段
FieldTypeDescription
ad_group_criterion.criterion_idINT64条件 ID
ad_group_criterion.keyword.textSTRING关键字文本
ad_group_criterion.keyword.match_typeENUMBROAD、PHRASE、EXACT
ad_group_criterion.statusENUMENABLED、PAUSED、REMOVED
ad_group_criterion.quality_info.quality_scoreINT32质量得分（1-10）
ad_group_criterion.quality_info.creative_quality_scoreENUMBELOW_AVERAGE、AVERAGE、ABOVE_AVERAGE
ad_group_criterion.quality_info.post_click_quality_scoreENUM落地页体验
ad_group_criterion.quality_info.search_predicted_ctrENUM预期 CTR
ad_group_criterion.effective_cpc_bid_microsINT64有效 CPC 出价
ad_group_criterion.position_estimates.first_page_cpc_microsINT64预估首页 CPC
搜索词字段
FieldTypeDescription
search_term_view.search_termSTRING用户实际搜索查询
search_term_view.statusENUMADDED、EXCLUDED、ADDED_EXCLUDED、NONE
指标
字段类型描述
metrics.impressionsINT64展示次数
metrics.clicksINT64点击次数
metrics.cost_microsINT64费用，单位为微（除以 1,000,000）
metrics.ctrDOUBLE点击率
metrics.average_cpcDOUBLE平均 CPC，单位为微
metrics.average_cpmDOUBLE平均 CPM，单位为微
metrics.conversionsDOUBLE转化次数
metrics.conversions_valueDOUBLE转化总价值
metrics.cost_per_conversionDOUBLE单次转化费用，单位为微
metrics.all_conversionsDOUBLE所有转化次数（包括跨设备转化）
metrics.all_conversions_valueDOUBLE所有转化价值
metrics.view_through_conversionsINT64浏览后转化次数
metrics.search_impression_shareDOUBLE搜索展示份额（0.0-1.0）
metrics.search_top_impression_shareDOUBLE顶部展示份额
metrics.search_absolute_top_impression_shareDOUBLE绝对顶部展示份额
metrics.search_budget_lost_impression_shareDOUBLE因预算损失的展示份额
metrics.search_rank_lost_impression_shareDOUBLE因排名损失的展示份额
metrics.interaction_rateDOUBLE互动率
metrics.interactionsINT64互动次数
metrics.video_viewsINT64视频观看次数
metrics.video_view_rateDOUBLE视频观看率
metrics.invalid_clicksINT64Google 过滤的无效点击次数
细分
字段类型描述
segments.dateDATE日期（YYYY-MM-DD）
segments.day_of_weekENUM从 MONDAY 到 SUNDAY
segments.monthDATE月份的第一天
segments.quarterDATE季度的第一天
segments.yearINT32年份
segments.hourINT32一天中的小时（0-23）
segments.deviceENUMDESKTOP、MOBILE、TABLET、OTHER
segments.ad_network_typeENUMSEARCH、SEARCH_PARTNERS、CONTENT、YOUTUBE_SEARCH、YOUTUBE_WATCH
segments.slotENUMTOP、OTHER
segments.conversion_actionRESOURCE转化操作资源名称
segments.conversion_action_nameSTRING转化操作名称
segments.conversion_action_categoryENUM转化操作类别
segments.click_typeENUMURL_CLICKS、CALLS、SITELINKS 等
segments.keyword.info.textSTRING关键字文本（在 search_term_view 中）
segments.keyword.info.match_typeENUM关键字匹配类型

WHERE 子句运算符

比较运算符
运算符示例
=campaign.status = 'ENABLED'
!=campaign.status != 'REMOVED'
>metrics.impressions > 100
<metrics.ctr < 0.02
>=metrics.clicks >= 10
<=metrics.cost_micros <= 5000000
集合运算符
运算符示例
INcampaign.status IN ('ENABLED', 'PAUSED')
NOT INcampaign.advertising_channel_type NOT IN ('VIDEO', 'DISPLAY')
CONTAINS ANYcampaign.labels CONTAINS ANY ('customers/123/labels/456')
CONTAINS ALLcampaign.labels CONTAINS ALL ('..label1..', '..label2..')
CONTAINS NONEcampaign.labels CONTAINS NONE ('customers/123/labels/456')
字符串运算符
运算符示例
LIKEcampaign.name LIKE '%Brand%'
NOT LIKEcampaign.name NOT LIKE '%Test%'
空值检查
运算符示例
IS NULLad_group_criterion.quality_info.quality_score IS NULL
IS NOT NULLad_group_criterion.quality_info.quality_score IS NOT NULL
范围运算符
运算符示例
BETWEENsegments.date BETWEEN '2025-01-01' AND '2025-01-31'
DURINGsegments.date DURING LAST_30_DAYS
日期宏（DURING）
宏说明
TODAY仅今天
YESTERDAY仅昨天
LAST_7_DAYS过去 7 天（不包括今天）
LAST_14_DAYS过去 14 天
LAST_30_DAYS过去 30 天
LAST_BUSINESS_WEEK上周周一至周五
THIS_WEEK_MON_TODAY本周周一至今天
THIS_WEEK_SUN_TODAY本周周日至今天
THIS_MONTH本月第一天至今天
LAST_MONTH上一个完整月份

常见查询模式

广告系列效果报告
SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  campaign.advertising_channel_type,
  campaign.bidding_strategy_type,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status != 'REMOVED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
搜索字词报告（识别否定关键字）
SELECT
  search_term_view.search_term,
  search_term_view.status,
  segments.keyword.info.text,
  segments.keyword.info.match_type,
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM search_term_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 10
ORDER BY metrics.cost_micros DESC
LIMIT 1000

筛选费用高但零转化的字词，以建立否定关键字列表。

质量得分分析
SELECT
  campaign.name,
  ad_group.name,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.quality_info.quality_score,
  ad_group_criterion.quality_info.creative_quality_score,
  ad_group_criterion.quality_info.post_click_quality_score,
  ad_group_criterion.quality_info.search_predicted_ctr,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM keyword_view
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND ad_group_criterion.quality_info.quality_score IS NOT NULL
  AND segments.date DURING LAST_30_DAYS
ORDER BY ad_group_criterion.quality_info.quality_score ASC
着陆页效果
SELECT
  landing_page_view.unexpanded_final_url,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM landing_page_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.clicks > 0
ORDER BY metrics.clicks DESC
LIMIT 100
设备细分
SELECT
  campaign.name,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.name, segments.device
地理位置效果
SELECT
  geographic_view.country_criterion_id,
  geographic_view.location_type,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.cost_per_conversion
FROM geographic_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 0
ORDER BY metrics.cost_micros DESC
LIMIT 200
广告文案效果（RSA 素材级别）
SELECT
  campaign.name,
  ad_group.name,
  ad_group_ad.ad.id,
  ad_group_ad.ad.responsive_search_ad.headlines,
  ad_group_ad.ad.responsive_search_ad.descriptions,
  ad_group_ad.ad.final_urls,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions
FROM ad_group_ad
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_ad.status = 'ENABLED'
  AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC

素材级别的效果：

SELECT
  campaign.name,
  ad_group.name,
  ad_group_ad_asset_view.field_type,
  ad_group_ad_asset_view.performance_label,
  asset.text_asset.text,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions
FROM ad_group_ad_asset_view
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY ad_group_ad_asset_view.performance_label DESC, metrics.impressions DESC
预算利用率／展示份额
SELECT
  campaign.name,
  campaign.campaign_budget,
  campaign_budget.amount_micros,
  campaign.bidding_strategy_type,
  metrics.impressions,
  metrics.cost_micros,
  metrics.search_impression_share,
  metrics.search_top_impression_share,
  metrics.search_absolute_top_impression_share,
  metrics.search_budget_lost_impression_share,
  metrics.search_rank_lost_impression_share
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND campaign.advertising_channel_type = 'SEARCH'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.search_budget_lost_impression_share DESC
转化操作细分
SELECT
  campaign.name,
  segments.conversion_action_name,
  segments.conversion_action_category,
  metrics.conversions,
  metrics.conversions_value,
  metrics.all_conversions,
  metrics.all_conversions_value,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.conversions > 0
ORDER BY metrics.conversions DESC
更改历史审核
SELECT
  change_event.change_date_time,
  change_event.change_resource_type,
  change_event.change_resource_name,
  change_event.resource_change_operation,
  change_event.changed_fields,
  change_event.old_resource,
  change_event.new_resource,
  change_event.user_email
FROM change_event
WHERE change_event.change_date_time DURING LAST_14_DAYS
  AND change_event.change_resource_type IN (
    'CAMPAIGN', 'AD_GROUP', 'AD_GROUP_AD',
    'AD_GROUP_CRITERION', 'CAMPAIGN_BUDGET'
  )
ORDER BY change_event.change_date_time DESC
LIMIT 500

注意事项

cost_micros 需要除法换算

所有费用字段的单位均为 micros（货币单位的 1/1,000,000）：

Actual cost = metrics.cost_micros / 1,000,000
Actual CPC  = metrics.average_cpc / 1,000,000

例如：cost_micros = 5430000 表示 $5.43。

细分与指标的兼容性
  • segments.conversion_action — 展示次数／点击次数会在每个转化操作行中重复出现。请勿将它们相加。
  • segments.click_type — 点击次数和展示次数会按点击类型拆分。求和会导致重复计数。
  • segments.slot — 仅适用于搜索广告系列。
  • segments.hour — 对于某些资源，不能与 segments.date 组合使用。
  • 不确定时，请查看 Google Ads API 字段兼容性矩阵。
日期范围要求
  • 含有 metrics.* 字段的查询需要指定日期范围（segments.date DURING ... 或 BETWEEN）。
  • 仅查询资源（不含指标）时无需指定日期范围。
枚举值

枚举字段必须使用字符串常量名称：

  • CampaignStatus： ENABLED、PAUSED、REMOVED
  • AdGroupStatus： ENABLED、PAUSED、REMOVED
  • AdvertisingChannelType： SEARCH、DISPLAY、SHOPPING、VIDEO、PERFORMANCE_MAX、MULTI_CHANNEL、LOCAL、SMART、HOTEL、DISCOVERY
  • KeywordMatchType： BROAD、PHRASE、EXACT
  • BiddingStrategyType： TARGET_CPA、TARGET_ROAS、MAXIMIZE_CONVERSIONS、MAXIMIZE_CONVERSION_VALUE、MANUAL_CPC、ENHANCED_CPC、TARGET_IMPRESSION_SHARE
  • Device： DESKTOP、MOBILE、TABLET、CONNECTED_TV、OTHER
  • QualityScoreBucket： BELOW_AVERAGE、AVERAGE、ABOVE_AVERAGE
速率限制
  • 标准访问权限： 每天 15,000 个请求，每分钟 1,600 个操作。
  • 基础访问权限： 每天 10,000 个请求。
  • 对于大型结果集，请使用 SearchStream（无论结果集大小如何，都只计为一个操作）。
其他注意事项
  • 不支持 OR： 所有 WHERE 条件均以 AND 连接。请使用 IN 或分别执行查询。
  • 不支持连接： GAQL 查询仅针对单个资源运行。
  • 不支持 GROUP BY： 聚合由所选字段和细分隐式完成。
  • 不支持别名： GAQL 中不能使用 AS。
  • 不支持算术运算： 请在客户端计算 cost_micros / 1000000。
  • 细分自动分组： 添加细分会按该维度拆分行。
  • 已移除的资源： 默认排除。若要包含，请显式添加筛选条件。
  • PARAMETERS 子句： 草稿使用 include_drafts = true；使用 omit_unselected_resource_names = true 可缩小响应大小。

资源

评论

支持 Markdown