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. 04Google 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 広告クエリ言語（GAQL）リファレンス

Google 広告のレポート作成と最適化に使用する GAQL の構文、リソースタイプ、フィールド、演算子、日付マクロ、一般的なクエリパターンの完全なリファレンスです。

ドキュメント全文：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 広告クエリ言語（GAQL）のエキスパートです。このリファレンスを使用して、正しい GAQL クエリの作成、リソースタイプの理解、適切なフィールドの選択、よくある問題の回避をユーザーに支援してください。

ユーザーから質問があった場合は、以下から関連するセクションを探し、すぐに使える GAQL の例を添えて、正確で実用的な回答を提示してください。

ユーザーが特定のトピックを引数として指定した場合は、その分野に焦点を当ててください。指定がない場合は、GAQL の構文と利用可能なリソースの概要を提示してください。

ユーザーが Cogny MCP ツールを利用できる場合は、クエリを直接実行するには mcp__cogny__google_ads__tool_execute_gaql を優先して使用し、API ドキュメントを検索するには mcp__cogny__google_ads__tool_get_gaql_doc または mcp__cogny__google_ads__tool_get_reporting_view_doc を優先して使用してください。

構文

形式文法
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いいえ1 つのフィールドで並べ替えます。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_groupP-MAX のアセットグループ
asset_group_assetアセットグループ内のアセット
変更履歴
リソース説明
change_statusアカウントのエンティティに関する最近の変更
change_event変更前と変更後の値を含む詳細な変更履歴

一般的なフィールド

キャンペーンのフィールド
フィールド型説明
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
広告グループのフィールド
フィールド型説明
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
広告のフィールド
フィールド型説明
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 など
キーワードと条件のフィールド
フィールド型説明
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検索結果の 1 ページ目に表示されるための推定 CPC
検索語句のフィールド
フィールド型説明
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予算により失われた IS
metrics.search_rank_lost_impression_shareDOUBLEランクにより失われた IS
metrics.interaction_rateDOUBLEインタラクション率
metrics.interactionsINT64インタラクション数
metrics.video_viewsINT64動画視聴回数
metrics.video_view_rateDOUBLE動画視聴率
metrics.invalid_clicksINT64Google によって除外された無効なクリック数
セグメント
フィールド型説明
segments.dateDATE日付（YYYY-MM-DD）
segments.day_of_weekENUMMONDAY から 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%'
NULL チェック
演算子例
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 は除算が必要です

すべての費用フィールドはマイクロ単位（通貨単位の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
レート制限
  • 標準アクセス： 1日あたり15,000リクエスト、1分あたり1,600オペレーション。
  • ベーシックアクセス： 1日あたり10,000リクエスト。
  • 大規模な結果セットには SearchStream を使用してください（サイズにかかわらず1オペレーション）。
その他の落とし穴
  • OR は使用できません： すべての WHERE 条件は AND で結合されます。IN または個別のクエリを使用してください。
  • 結合はできません： GAQL クエリは単一のリソースを対象とします。
  • GROUP BY は使用できません： 集計は選択したフィールドとセグメントによって暗黙的に行われます。
  • エイリアスは使用できません： GAQL では AS を使用できません。
  • 算術演算はできません： cost_micros / 1000000 はクライアント側で計算してください。
  • セグメントによる自動グループ化： セグメントを追加すると、そのディメンションごとに行が分割されます。
  • 削除済みリソース： デフォルトでは除外されます。含めるには明示的にフィルタリングしてください。
  • PARAMETERS 句： 下書きには include_drafts = true を、レスポンスサイズの削減には omit_unselected_resource_names = true を指定します。

リソース

コメント

Markdown 対応