Back to Details

gaql-query-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GAQL Query Patterns

GAQL 查询模式

Ready-to-use GAQL (Google Ads Query Language) query templates for common PPC analysis tasks.
用于常见 PPC 分析任务的开箱即用 GAQL（Google Ads Query Language）查询模板。

What This Skill Deliberately Does NOT Do

本 Skill 刻意不做的操作

  • Run the queries. These are copy-paste templates, not a runner — paste them into your own API client, Google Ads Scripts, or 
    google-ads-query
     to actually execute and export.
  • Mutate anything. Every template is a read-only 
    SELECT
    ; nothing here changes an account.
  • Cover change-history queries. Pulling what changed and when needs a finite date window and a 
    LIMIT
    , and lives in 
    change-history-checker
     — a windowless change query won't run.
  • Diagnose the results. The "Use for" and "Interpreting results" notes point you at the analysis; the actual root-causing lives in the diagnostic skills (e.g. 
    impression-share-diagnostics
     for the impression-share query).
  • 执行查询。 这些是可复制粘贴的模板，而不是查询运行器——请将它们粘贴到你自己的 API 客户端、Google Ads Scripts，或 
    google-ads-query
     中，以实际执行和导出。
  • 修改任何数据。 每个模板都是只读 
    SELECT
    ；这里的内容不会更改账户。
  • 涵盖变更历史查询。 查询变更内容及变更时间需要设置有限的日期窗口和 
    LIMIT
    ，相关功能位于 
    change-history-checker
    ——没有日期窗口的变更查询无法运行。
  • 诊断结果。 “适用于”和“结果解读”说明会指出分析方向；实际根因分析位于诊断类 Skills 中（例如，展示次数份额查询可使用 
    impression-share-diagnostics
    ）。

Campaign Queries

广告系列查询

7-Day Campaign Spend Analysis

7 天广告系列支出分析

sql
SELECT
    campaign.id,
    campaign.name,
    campaign.status,
    campaign.advertising_channel_type,
    campaign.bidding_strategy_type,
    campaign_budget.amount_micros,
    campaign_budget.explicitly_shared,
    metrics.cost_micros,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.conversions_value
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY campaign.name
Use for: Recent spend analysis, budget utilization, campaign health checks
sql
SELECT
    campaign.id,
    campaign.name,
    campaign.status,
    campaign.advertising_channel_type,
    campaign.bidding_strategy_type,
    campaign_budget.amount_micros,
    campaign_budget.explicitly_shared,
    metrics.cost_micros,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.conversions_value
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY campaign.name
适用于： 近期支出分析、预算利用情况、广告系列健康状况检查

Month-to-Date Pacing

本月至今预算节奏

sql
SELECT
    campaign.id,
    campaign.name,
    campaign_budget.amount_micros,
    metrics.cost_micros
FROM campaign
WHERE segments.date DURING THIS_MONTH
ORDER BY campaign.name
Use for: Monthly pacing calculations, budget tracking
sql
SELECT
    campaign.id,
    campaign.name,
    campaign_budget.amount_micros,
    metrics.cost_micros
FROM campaign
WHERE segments.date DURING THIS_MONTH
ORDER BY campaign.name
适用于： 月度预算节奏计算、预算跟踪

Campaign Settings Audit

广告系列设置审计

sql
SELECT
    campaign.id,
    campaign.name,
    campaign.status,
    campaign.advertising_channel_type,
    campaign.bidding_strategy_type,
    campaign.target_cpa.target_cpa_micros,
    campaign.target_roas.target_roas,
    campaign_budget.amount_micros,
    campaign_budget.explicitly_shared
FROM campaign
WHERE campaign.status = 'ENABLED'
Use for: Configuration audits, bidding strategy checks, budget review
sql
SELECT
    campaign.id,
    campaign.name,
    campaign.status,
    campaign.advertising_channel_type,
    campaign.bidding_strategy_type,
    campaign.target_cpa.target_cpa_micros,
    campaign.target_roas.target_roas,
    campaign_budget.amount_micros,
    campaign_budget.explicitly_shared
FROM campaign
WHERE campaign.status = 'ENABLED'
适用于： 配置审计、出价策略检查、预算审查

Impression Share

展示次数份额

Search Impression Share Analysis

搜索广告展示次数份额分析

sql
SELECT
    campaign.id,
    campaign.name,
    campaign.advertising_channel_type,
    metrics.search_impression_share,
    metrics.search_budget_lost_impression_share,
    metrics.search_rank_lost_impression_share,
    metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.advertising_channel_type IN ('SEARCH', 'PERFORMANCE_MAX')
ORDER BY metrics.search_budget_lost_impression_share DESC
Use for: Diagnosing underspending, identifying budget constraints vs. quality issues
Interpreting results:
  • High Budget Lost IS → increase budget to capture more impressions
  • High Rank Lost IS → quality/relevance issue (not a budget problem)
  • Both high → budget is primary constraint, but quality also needs work
sql
SELECT
    campaign.id,
    campaign.name,
    campaign.advertising_channel_type,
    metrics.search_impression_share,
    metrics.search_budget_lost_impression_share,
    metrics.search_rank_lost_impression_share,
    metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.advertising_channel_type IN ('SEARCH', 'PERFORMANCE_MAX')
ORDER BY metrics.search_budget_lost_impression_share DESC
适用于： 诊断投放不足，区分预算限制与质量问题
结果解读：
  • 预算损失展示次数份额较高 → 增加预算以获取更多展示次数
  • 排名损失展示次数份额较高 → 属于质量或相关性问题（而非预算问题）
  • 两者都高 → 预算是主要限制因素，但质量也需要改进

Search Terms

搜索字词

Search Term Report (Last 30 Days)

搜索字词报告（过去 30 天）

sql
SELECT
    search_term_view.search_term,
    campaign.name,
    ad_group.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions,
    search_term_view.status
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 0
ORDER BY metrics.cost_micros DESC
Use for: Negative keyword discovery, search term audits, intent analysis
sql
SELECT
    search_term_view.search_term,
    campaign.name,
    ad_group.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions,
    search_term_view.status
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 0
ORDER BY metrics.cost_micros DESC
适用于： 发现否定关键词、搜索字词审计、搜索意图分析

High-Spend Non-Converting Search Terms

高支出无转化搜索字词

sql
SELECT
    search_term_view.search_term,
    campaign.name,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions = 0
  AND metrics.cost_micros > 0
ORDER BY metrics.cost_micros DESC
Use for: Finding wasted spend, negative keyword candidates
sql
SELECT
    search_term_view.search_term,
    campaign.name,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions = 0
  AND metrics.cost_micros > 0
ORDER BY metrics.cost_micros DESC
适用于： 查找浪费的支出、筛选否定关键词候选项

Keywords

关键词

Keyword Performance with Quality Score

关键词表现与质量得分

sql
SELECT
    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 segments.date DURING LAST_30_DAYS
  AND ad_group_criterion.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC
Use for: Quality score audits, keyword performance analysis
sql
SELECT
    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 segments.date DURING LAST_30_DAYS
  AND ad_group_criterion.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC
适用于： 质量得分审计、关键词表现分析

Non-Serving Keywords (Zero Impressions)

未投放关键词（零展示次数）

sql
SELECT
    campaign.name,
    ad_group.name,
    ad_group_criterion.keyword.text,
    ad_group_criterion.keyword.match_type,
    ad_group_criterion.status,
    metrics.impressions
FROM keyword_view
WHERE segments.date DURING LAST_180_DAYS
  AND campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND metrics.impressions = 0
Use for: Finding dead keywords to clean up, account hygiene
sql
SELECT
    campaign.name,
    ad_group.name,
    ad_group_criterion.keyword.text,
    ad_group_criterion.keyword.match_type,
    ad_group_criterion.status,
    metrics.impressions
FROM keyword_view
WHERE segments.date DURING LAST_180_DAYS
  AND campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND metrics.impressions = 0
适用于： 查找需要清理的失效关键词、维护账户整洁

Ads

广告

RSA Performance

RSA 表现

sql
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_strength,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.cost_micros
FROM ad_group_ad
WHERE segments.date DURING LAST_30_DAYS
  AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'
  AND ad_group_ad.status = 'ENABLED'
ORDER BY metrics.impressions DESC
Use for: Ad performance review, RSA optimization
sql
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_strength,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.cost_micros
FROM ad_group_ad
WHERE segments.date DURING LAST_30_DAYS
  AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'
  AND ad_group_ad.status = 'ENABLED'
ORDER BY metrics.impressions DESC
适用于： 广告表现审查、RSA 优化

Conversions

转化

Conversion Actions List

转化操作列表

sql
SELECT
    conversion_action.id,
    conversion_action.name,
    conversion_action.type,
    conversion_action.status,
    conversion_action.category,
    conversion_action.value_settings.default_value,
    conversion_action.counting_type,
    conversion_action.attribution_model_settings.attribution_model
FROM conversion_action
WHERE conversion_action.status = 'ENABLED'
ORDER BY conversion_action.name
Use for: Conversion tracking audits, identifying misconfigured actions
sql
SELECT
    conversion_action.id,
    conversion_action.name,
    conversion_action.type,
    conversion_action.status,
    conversion_action.category,
    conversion_action.value_settings.default_value,
    conversion_action.counting_type,
    conversion_action.attribution_model_settings.attribution_model
FROM conversion_action
WHERE conversion_action.status = 'ENABLED'
ORDER BY conversion_action.name
适用于： 转化跟踪审计、识别配置错误的转化操作

Conversion Performance by Action

按操作划分的转化表现

sql
SELECT
    segments.conversion_action_name,
    segments.conversion_action_category,
    metrics.conversions,
    metrics.conversions_value,
    metrics.all_conversions,
    metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.conversions DESC
Use for: Understanding which conversion actions are firing, value distribution
sql
SELECT
    segments.conversion_action_name,
    segments.conversion_action_category,
    metrics.conversions,
    metrics.conversions_value,
    metrics.all_conversions,
    metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.conversions DESC
适用于： 了解哪些转化操作正在触发、价值分布

Geographic Performance

地理表现

sql
SELECT
    geographic_view.country_criterion_id,
    geographic_view.location_type,
    campaign.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions
FROM geographic_view
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
Use for: Geographic bid adjustments, location targeting audits
sql
SELECT
    geographic_view.country_criterion_id,
    geographic_view.location_type,
    campaign.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions
FROM geographic_view
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
适用于： 地理出价调整、定位目标审计

Device Performance

设备表现

sql
SELECT
    campaign.name,
    segments.device,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions,
    metrics.average_cpc
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY campaign.name, segments.device
Use for: Device bid adjustments, mobile vs. desktop analysis
sql
SELECT
    campaign.name,
    segments.device,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions,
    metrics.average_cpc
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY campaign.name, segments.device
适用于： 设备出价调整、移动端与桌面端分析

Account-Level Summary

账户级摘要

sql
SELECT
    customer.id,
    customer.descriptive_name,
    metrics.cost_micros,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.conversions_value
FROM customer
WHERE segments.date DURING LAST_30_DAYS
Use for: High-level account overview, executive reporting
sql
SELECT
    customer.id,
    customer.descriptive_name,
    metrics.cost_micros,
    metrics.impressions,
    metrics.clicks,
    metrics.conversions,
    metrics.conversions_value
FROM customer
WHERE segments.date DURING LAST_30_DAYS
适用于： 账户整体概览、管理层报告

Date Range Reference

日期范围参考

KeywordMeaning
YESTERDAY
Yesterday only
TODAY
Today only
LAST_7_DAYS
Last 7 days
LAST_14_DAYS
Last 14 days
LAST_30_DAYS
Last 30 days
THIS_MONTH
Current month to date
LAST_MONTH
Previous calendar month
THIS_WEEK_MON_TODAY
This week (Monday to today)
关键字含义
YESTERDAY
仅昨天
TODAY
仅今天
LAST_7_DAYS
过去 7 天
LAST_14_DAYS
过去 14 天
LAST_30_DAYS
过去 30 天
THIS_MONTH
本月截至今日
LAST_MONTH
上一个自然月
THIS_WEEK_MON_TODAY
本周（周一至今天）

Key Field Notes

关键字段说明

Micros Conversion

Micros 换算

The API returns monetary values in micros (1,000,000 = $1):
50000000 micros = $50.00
1234567 micros = $1.23
Always divide by 1,000,000 when displaying to users.
API 返回的货币值以 micros 为单位（1,000,000 = $1）：
50000000 micros = $50.00
1234567 micros = $1.23
向用户展示时，始终除以 1,000,000。

Impression Share Returns Decimals

展示次数份额返回小数值

The API returns impression share as decimals (0.0 - 1.0), NOT percentages:
  • API value 
    0.2464
    = 24.64% actual impression share
  • Always multiply by 100 when displaying
API 返回的展示次数份额是小数（0.0 - 1.0），而不是百分比：
  • API 值 
    0.2464
    = 实际展示次数份额 24.64%
  • 展示时始终乘以 100

Metrics Require Date Segmentation

指标需要日期分段

Any query with 
metrics.*
fields MUST include a 
WHERE segments.date
clause. Without it, the query will fail.
任何包含 
metrics.*
字段的查询都必须包含 
WHERE segments.date
子句。否则，查询将失败。

Impression Share is Search/PMax Only

展示次数份额仅适用于 Search/PMax

search_impression_share
, 
search_budget_lost_impression_share
, and 
search_rank_lost_impression_share
are only available for Search and Performance Max campaigns.
search_impression_share
、
search_budget_lost_impression_share
和 
search_rank_lost_impression_share
仅适用于 Search 和 Performance Max 广告系列。

AND vs OR

AND 与 OR

GAQL doesn't support 
OR
. Use 
IN
instead:
sql
-- Wrong
WHERE campaign.status = 'ENABLED' OR campaign.status = 'PAUSED'

-- Correct
WHERE campaign.status IN ('ENABLED', 'PAUSED')
GAQL 不支持 
OR
。请改用 
IN
：
sql
-- Wrong
WHERE campaign.status = 'ENABLED' OR campaign.status = 'PAUSED'

-- Correct
WHERE campaign.status IN ('ENABLED', 'PAUSED')

When to Load Other Skills

何时加载其他 Skills

SkillWhen
google-ads-query
To run these templates against an account and export the results to CSV — this skill is the templates, that one is the runner
change-history-checker
For "what changed and when" queries — they require a finite date window (90-day / 30-day) and a 
LIMIT
that these general templates don't carry
impression-share-diagnostics
To interpret the impression-share query — Search IS, Budget Lost IS, and Rank Lost IS root-causing lives there
Several skills reach for these templates when they outgrow their own — 
underspending-investigation
, 
budget-recommendation-calculator
, and 
mcc-hack-audit
 all point back here for custom GAQL.
Skill何时使用
google-ads-query
用于针对账户运行这些模板并将结果导出为 CSV——本 Skill 提供模板，该 Skill 负责执行
change-history-checker
用于查询“变更内容及变更时间”——这些查询需要有限日期窗口（90 天或 30 天）和 
LIMIT
，而这些通用模板未包含这些条件
impression-share-diagnostics
用于解读展示次数份额查询——Search IS、Budget Lost IS 和 Rank Lost IS 的根因分析应在该 Skill 中完成
当以下 Skills 超出自身适用范围时，会转用这些模板——
underspending-investigation
、
budget-recommendation-calculator
 和 
mcc-hack-audit
 都会指向此处以获取自定义 GAQL。