クエリは、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 つだけ指定できます。
- クエリの他のすべての句で使用できるフィールドを定義します。
貢献度が割り当てられたリソース
帰属先リソースが利用可能な場合、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
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
レポートの分割について詳しくは、セグメンテーションをご覧ください。
大文字と小文字の区別
文字列値をフィルタリングする場合、結果を正しくフィルタリングするには、各演算子のデフォルトの大文字と小文字が重要な役割を果たします。
次の表に、各演算子のデフォルトの大文字と小文字の区別を示します。
デフォルトの大文字と小文字の区別 | |
---|---|
=/!= |
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"