查詢由多個子句組成:SELECT
、FROM
、WHERE
、ORDER BY
、LIMIT
和 PARAMETERS
。
子句使用合併為單一查詢要求的「欄位名稱」、「資源名稱」、「運算子」、「條件」和「順序」。
基本上,如要建立查詢,請執行下列操作:
- 指定要從哪個資源擷取資料。
- 新增欄位和指標來定義您要傳回的資料。
- 新增區隔即可將結果分組。
- 新增已歸因的資源,以隱含方式彙整相關資源資料。
- 篩選、排序及限制結果數量。
SELECT
子句
SELECT
子句:
- 是查詢中的「必要」子句。
- 指定要在要求中擷取的一組欄位。
- 取得以半形逗號分隔的資源欄位、自訂欄、Floodlight 自訂變數、區隔欄位和指標清單,然後傳回回應中的值。
以下查詢範例說明如何選取 campaign
資源的屬性:
SELECT
campaign.id,
campaign.name
FROM campaign
多個欄位類型
您可以在同一個要求中要求其他欄位類型。
以下查詢範例顯示了下列組合的單一查詢:
- 資源欄位:
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
的查詢「不應」加入此值。 - 指定查詢傳回的主要資源。
- 只能指定單一資源。
- 定義您可以在查詢中所有其他子句中使用的欄位。
歸因資源
如果有已歸因的資源,這些歸因資源會以隱含形式與您在 FROM
子句中指定的資源彙整。您只需將屬性加入 SELECT
子句,即可傳回其值。
這個範例查詢會同時傳回廣告群組 ID 和廣告活動 ID,因為 campaign
是 ad_group
資源的歸因資源。
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
欄位。
在以下查詢範例中,由於已選取 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
(遞減)。預設值為遞增。
此查詢範例按點擊次數遞減排序 (由高至低):
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 天內曝光次數最高的五個廣告活動:
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
此查詢範例會傳回 campaign.resource_name
欄位,因為 SELECT
子句明確要求此欄位:
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"
這個查詢範例會傳回智利披索 (CLP) 的 cost_micros 指標。
SELECT
campaign.name,
metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"