クエリの構造と句

クエリは、SELECT、FROM、WHERE、ORDER BY、LIMIT、PARAMETERS の句で構成されます。

句では、フィールド名、リソース名、演算子、条件、順序付けを使用し、これらを組み合わせて 1 つのクエリ リクエストを作成します。

クエリを作成する基本的な手順は次のとおりです。

• データを取得するリソースを指定します。
• フィールドと指標を追加して、返すデータを定義します。
• 結果をグループ化するには、セグメントを追加します。
• 貢献度が割り当てられたリソースを追加すると、関連するリソースデータを暗黙的に結合できます。
• 結果をフィルタ、並べ替え、制限します。

SELECT 句

SELECT 句:

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

次のクエリの例は、campaign リソースの属性を選択する方法を示しています。

SELECT
  campaign.id,
  campaign.name
FROM campaign

複数のフィールド タイプ

1 回のリクエストでさまざまなフィールド タイプをリクエストできます。

次のクエリの例は、次の組み合わせを含む 1 つのクエリを示しています。

• リソース フィールド: campaign.id、campaign.name、bidding_strategy.id、bidding_strategy.name。
• セグメント フィールド: segments.device と segments.date。
• 指標フィールド: metrics.impressions と metrics.clicks。

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

検索レポートのセグメント化の詳細については、セグメンテーションをご覧ください。

メインリソース フィールド

通常、SELECT 句にメインのリソース フィールドを含めますが、これは省略することもできます（必須ではありません）。

次のサンプルクエリでは、メインリソース フィールド（ad_group.status）を使用して、結果をフィルタリングするだけです。

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

カスタム Floodlight 変数

カスタム Floodlight 変数は、その ID を使って SELECT 句に含めることができます。

この例では、キャンペーン リソースの ID が 123454321 のカスタム変数がクエリに含まれています。

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

カスタム列

ID を使用して SELECT 句にカスタム列を含めることができます。

この例では、クエリにキャンペーン リソースの ID が 12345678 のカスタム列が含まれています。

SELECT
  custom_columns.id[12345678]
FROM campaign

詳しくは、カスタム列 ID を取得する方法をご覧ください。

指標フィールド

SELECT 句にリソースの他のフィールドを含めずに、特定のリソースの指標フィールドを選択できます。

次のクエリ例では、campaign リソースの impressions 指標と clicks 指標を選択します。

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

クエリで使用できる指標フィールドの一覧については、metrics をご覧ください。

セグメント フィールド

SELECT 句で付属のリソース フィールドや指標を指定せずに、セグメント フィールドを選択できます。

この例のクエリでは、結果がデバイス別に分割されています。

SELECT segments.device
FROM campaign

クエリで使用できるセグメント フィールドの一覧については、segments をご覧ください。

禁止フィールド

SELECT 句で次のフィールドは使用できません。

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

各リソースのこれらの情報を確認できる場所について詳しくは、リファレンス ドキュメントをご覧ください。

FROM 句

FROM 句:

• SearchAds360Service に対するクエリ（Search と SearchStream の両方のメソッド）に必須の句です。
• SearchAds360FieldService に対するクエリには含めないでください。
• クエリが返すメインリソースを指定します。
• リソースは 1 つだけ指定できます。
• クエリの他のすべての句で使用できるフィールドを定義します。

注: 参照セクションの各リソースページには、[Yes/No] 選択フィールドがあり、リソースが FROM 句で指定されているときに使用できないリソース フィールド、セグメント フィールド、指標フィールドを除外しています。

貢献度が割り当てられたリソース

帰属先リソースが利用可能な場合、FROM 句で指定したリソースと暗黙的に結合されます。それらの値を SELECT 句に追加するだけで、その値が返されます。

このサンプルクエリは、campaign が ad_group リソースの帰属付きリソースであるため、広告グループ ID とキャンペーン ID の両方を返します。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

注: すべてのリソースに、貢献度が割り当てられたリソースがあるわけではありません。[リファレンス] セクションには、各リソースで使用可能な帰属リソースの詳細が記載されています。

resource_name フィールド

FROM 句のメインリソースの resource_name フィールドが常に返されます。

次のクエリ例では、クエリで明示的に選択されていなくても ad_group.resource_name がレスポンスに含まれます。

SELECT ad_group.id
FROM ad_group

アトリビューション付きリソースの resource_name フィールドは、少なくとも 1 つのフィールドが選択されると返されます。

次のクエリ例では、campaign.id が選択されているため、レスポンスに campaign.resource_name が含まれます。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

注: FROM 句のリソースで別のリソースが segment としてリストされている場合、そのリソースの任意の属性を選択すると、セグメントとして機能します。

WHERE 句

WHERE 句:

• クエリのオプション句。
• リクエストのデータのフィルタリングとセグメント化の条件を指定します。条件は、FIELD_NAME OPERATOR VALUE（空白スペースで区切る）というパターンになります。
• 複数の条件を AND 区切りで区切って含めることができます。

次のサンプルクエリは、WHERE 句を使用して、特定の期間の impressions 指標を返す方法を示しています。

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

検索レポートのセグメント化の詳細については、セグメンテーションをご覧ください。

クエリで期間を指定する方法については、期間をご覧ください。

resource_name フィールドでフィルタ

resource_name フィールドを使用して、データのフィルタリングや並べ替えを行うことができます。

次のクエリの例では、campaign.resource_name フィールドを使用して、結果を特定のキャンペーンでフィルタしています。

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

複数の条件

複数の条件を組み合わせてデータをフィルタできます。

次のクエリ例では、過去 30 日間にモバイルで impressions 指標を使用しているすべてのキャンペーンについて、clicks 指標の数をリクエストします。

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

注: AND 区切り文字は演算子条件（WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"）間でのみ使用できます。1 つの演算子条件（WHERE segments.device != "DESKTOP" AND "MOBILE"）内では使用できません。

レポートの分割について詳しくは、セグメンテーションをご覧ください。

大文字と小文字の区別

文字列値をフィルタリングする場合、結果を正しくフィルタリングするには、各演算子のデフォルトの大文字と小文字が重要な役割を果たします。

次の表に、各演算子のデフォルトの大文字と小文字の区別を示します。

デフォルトの大文字と小文字の区別
=/!=	Case sensitive
IN/NOT IN	Case sensitive
LIKE/NOT LIKE	Case insensitive
CONTAINS (...)	Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH	Case sensitive

(?i) 修飾子を使用して、REGEXP_MATCH と NOT REGEXP_MATCH のデフォルトの感度を、大文字と小文字を区別しないものに変更できます。次に例を示します。

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

データのフィルタリングに使用できる演算子の一覧については、クエリ文法のリファレンスをご覧ください。

主要な期間セグメント

segments.date、segments.week、segments.month、segments.quarter、segments.year のセグメント フィールドは、コア日付セグメントと呼ばれます。

WHERE 句で主要な日付セグメントを使用して日付または期間を指定できます。

次のクエリの例では、WHERE 句の segments.date フィールドに DURING LAST_30_DAYS を指定しています。

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

コア日付セグメントの使用について詳しくは、[セグメンテーション] > [コア日付セグメント] をご覧ください。

禁止されているフィルタリング

次のフィルタは許可されていません。

• 未選択のセグメント フィールド（主要日付セグメントを除く）
• プリミティブ（Int64Value、StringValue など）を除くすべてのメッセージ タイプのフィールド。
• プリミティブ（Int64Value、StringValue など）を除く、任意のメッセージ タイプの繰り返しフィールドの属性。

ORDER BY 句

ORDER BY 句:

• クエリのオプション句。
• 結果が返される順序を指定します。順序は FIELD_NAME ORDERING_OPTION（空白スペースで区切る）のパターンに従います。
• ASC（昇順）または DESC（降順）の 2 つのオプションを使用できます。デフォルトは昇順です。

次のクエリの例では、キャンペーンをクリック数の降順（降順）で並べ替えます。

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

順序と上限を組み合わせる

ORDER BY 句を LIMIT 句と組み合わせて使用すると、結果を絞り込むことができます。

次のクエリの例では、過去 30 日間でインプレッション数が最も多い 5 つのキャンペーンが返されます。

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

禁止されている注文

次の条件での並べ替えは許可されていません。

• 選択されていないリソースの属性別。
• 選択されていない指標を基準にします。
• 選択されていないセグメント別。
• これらのフィールド タイプ:
  • MESSAGE
  • 繰り返しフィールド
  • 繰り返しフィールドの属性。

LIMIT 句

LIMIT 句:

• クエリのオプション句。
• クエリが返す結果の数を制限できます。

この句は、結果のサンプルやサマリーのみが必要な場合などに便利です。

次のクエリ例では、結果の合計数を 50 に制限しています。

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

PARAMETERS 句

PARAMETERS 句を使用すると、リクエストのメタ パラメータを指定できます。

回答案を含める

include_drafts パラメータは、下書きエンティティを結果に含めるかどうかを制御します。デフォルトは false です。下書きエンティティを含めるには、true に設定します。

次のクエリ例では、下書き用キャンペーンと通常のキャンペーンの両方が返されます。

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

未選択の resource_name を除外

omit_unselected_resource_names パラメータを使用すると、SELECT 句で明示的にリクエストされていないすべてのリソースの resource_name フィールドを除外できます。デフォルト値は false です。このパラメータを true に設定する場合は、プライマリ リソースのリソース名と SELECT 句の帰属先リソースのリソース名を明示的にリクエストすることをおすすめします。

次のサンプルクエリは、campaign.resource_name フィールドと customer.resource_name フィールドのどちらも SELECT 句に含まれていないため、これらのフィールドを返しません。

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

次のサンプルクエリは、SELECT 句で明示的にリクエストされているため、campaign.resource_name フィールドを返します。

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

指標で使用する通貨を変更する

metrics_currency パラメータを使用すると、SELECT 句に含まれる指標を計算するときに使用する通貨を指定できます。デフォルトでは、アカウントの現地通貨が使用されます。このパラメータを設定する場合は、ISO 4217 の 3 文字の通貨コードを使用する必要があります。例: USD、EUR。

次のクエリ例では、cost_micros 指標がアカウントの現地通貨で返されます。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

次のクエリ例では、cost_micros 指標がチリペソ（CLP）で返されます。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

詳細

• クエリ文法