クエリの構造

リソース、セグメント、指標の各フィールドに対するクエリは、GoogleAdsService Search メソッドまたは SearchStream メソッドに送信できます。Google 広告クエリ言語でクエリを作成するには、言語文法を使用します。クエリは複数の句で構成されます。

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

正しいデータを選択できるように、句ではフィールド名、リソース名、演算子、条件、並べ替えを使用できます。1 つのクエリにまとめたら、Google Ads API を使用してリクエストを送信できます。

句

動画: GAQL フィールドの互換性

SELECT

SELECT 句は、リクエストで取得するフィールドのセットを指定します。SELECT は、リソース フィールド、セグメント フィールド、指標のカンマ区切りのリストを取得し、レスポンスの値を返します。SELECT 句は、クエリで必須です。

次のサンプルクエリは、特定のリソースの属性を選択する例を示しています。

SELECT
  campaign.id,
  campaign.name
FROM campaign

次のように、1 つのリクエストで異なるフィールド タイプをリクエストできます。

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

  • リソース フィールド

    • campaign.id
    • campaign.name

  • リソース フィールド

    • bidding_strategy.id
    • bidding_strategy.name

  • セグメント フィールド

    • segments.device
    • segments.date

  • 指標

    • metrics.impressions
    • metrics.clicks

次の制限により、SELECT 句で使用できないフィールドがあります。

  • 選択できないフィールドをクエリする場合。これらのフィールドの Selectable メタデータ属性は false としてマークされます。
  • 繰り返しフィールドの属性を選択する場合。これらのフィールドの isRepeated メタデータ属性は true としてマークされます。
  • FROM 句で、指定されたリソースで使用できないフィールドを選択する。一部のリソースの属性は同時に選択できません。また、FROM 句のリソースで使用できるのは、すべての指標とセグメントのサブセットのみです。
  • 互換性のないセグメントまたは指標を選択している。詳細については、セグメンテーションのセクションをご覧ください。

上記の条件に関連する情報は、リファレンス ドキュメントまたは GoogleAdsFieldService で確認できます。

FROM

FROM 句は、返されるメインリソースを指定します。FROM 句のリソースは、指定されたクエリの他のすべての句で使用できるフィールドを定義します。FROM 句に指定できるリソースは 1 つだけです。FROM 句は、GoogleAdsService Search メソッドまたは SearchStream メソッドに対するクエリで必須です。ただし、GoogleAdsFieldService を使用する場合は、FROM 句を指定しないでください。

特定のクエリの FROM 句に存在できるリソースは 1 つだけですが、属性付きリソースのフィールドも使用できる場合があります。これらのリソースは FROM 句のリソースと暗黙的に結合されるため、値を返すには、これらのリソースの属性を SELECT 句に追加するだけで済みます。一部のリソースにはアトリビュート リソースがありません。次の例では、広告グループから広告グループ ID とキャンペーン ID の両方をリクエストできます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

メインリソースの resource_name フィールドが常に返されます。次の例では、クエリで明示的に選択されていないにもかかわらず、ad_group.resource_name がレスポンスに含まれています。

SELECT ad_group.id
FROM ad_group

少なくとも 1 つのフィールドが選択されている場合、他のリソースについても同じことが言えます。たとえば、campaign.resource_name は次のクエリのレスポンスに含まれます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE 句は、リクエストのデータをフィルタするときに適用する条件を指定します。WHERE 句を使用する場合、1 つ以上の条件を AND で区切って指定することができます。各条件は、field_name Operator value のパターンに従う必要があります。WHERE 句は、クエリで省略可能です。

以下は、与えられた期間の指標を返すために WHERE を使用したサンプルです。

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

複数の条件を組み合わせてデータをフィルタできます。このサンプルでは、過去 30 日間にモバイルでインプレッションが発生したすべてのキャンペーンのクリック数をリクエストしています。

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

WHERE 句のセグメントは SELECT 句に存在する必要があります。ただし、次の日付セグメント（コア日付セグメント）は例外です。

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

次のクエリでは、segments.date が選択されています。このセグメントはコア日付セグメントであるため、WHERE 句でコア日付セグメントで構成される有限の日付範囲を指定する必要があります。

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

上記の条件を満たすセグメントは、segments.date、segments.week、segments.month、segments.quarter、segments.year です。これらのセグメントのいずれかを選択した場合は、WHERE 句で少なくとも 1 つを使用する必要があります。

フィルタリングを行う際は、演算子の大文字と小文字の区別を考慮することが重要です。詳しくは、大文字と小文字の区別をご覧ください。

演算子の一覧については、言語文法をご覧ください。

ORDER BY

ORDER BY 句は、結果が返される順序を指定します。これにより、フィールド名に基づいてデータを昇順または降順に並べ替えることができます。各順序は、field_name の後に ASC または DESC を加えて指定します。ASC と DESC のどちらも指定されていない場合、順序はデフォルトで ASC になります。ORDER BY 句は、クエリで省略可能です。

次のクエリは、返されたキャンペーンをクリック数で降順に並べ替えます。

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

ORDER BY 句では、複数のフィールドをカンマで区切って指定できます。並べ替えは、クエリで指定されているのと同じ順序で行われます。たとえば、広告グループのデータを選択するこのクエリでは、キャンペーン名で昇順、インプレッション数で降順、クリック数で降順に結果が並べ替えられます。

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

LIMIT 句を使用すると、返される結果の数を指定できます。これは、概要だけが必要な場合に便利です。

たとえば、LIMIT を使用して、次のクエリの結果の総数を制限できます。

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS

PARAMETERS 句を使用すると、リクエストのメタパラメータを指定できます。これらのパラメータは、返される行の種類に影響を与える場合があります。

次のメタパラメータがサポートされています。

include_drafts

下書きエンティティを返すことを許可するには、include_drafts を true に設定します。デフォルト値は false です。

たとえば、次のクエリは、通常のキャンペーンとともに下書き用キャンペーンを取得します。

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

omit_unselected_resource_names を true に設定して、SELECT 句で明示的にリクエストされない限り、レスポンス内の各リソースタイプのリソース名が返されないようにします。デフォルトは false です。

omit_unselected_resource_names の例
SELECT
  campaign.name,
  customer.id
FROM campaign
 		Returned resources:
campaign.resource_name
customer.resource_name
omit_unselected_resource_names はデフォルトで false に設定されているため、すべての resource_name フィールドが返されます。		 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resources:
なし。
omit_unselected_resource_names は true として指定され、campaign.resource_name と customer.resource_name は SELECT 句の一部ではありません。		 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resource:
campaign.resource_name
omit_unselected_resource_names は true として指定され、campaign.resource_name は SELECT 句の一部としてリクエストされます。

その他の言語ルール

各句のサンプルに加えて、Google 広告クエリ言語には次のような特長があります。

  • メインリソース フィールドがクエリの SELECT 句内にある必要はありません。たとえば、データをフィルタするためには 1 つ以上のメインリソース フィールドのみを使用することができます。

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

  • メトリックは特定のリソースに対して排他的に選択できます。リソース内の他のフィールドはクエリに必要ありません。

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • セグメント フィールドは、付随するリソース フィールドや指標なしで選択できます。

    SELECT segments.device FROM campaign

  • resource_name フィールド（例: campaign.resource_name）を使用して、データをフィルタしたり並べ替えたりすることができます。

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
前へ
クエリ文法
次へ
期間