查詢結構和子句

查詢由多個子句組成：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 的查詢「不應」加入此值。
• 指定查詢傳回的主要資源。
• 只能指定單一資源。
• 定義您可以在查詢中所有其他子句中使用的欄位。

注意： 「參考資料」一節中每個資源頁面上都有「Yes/No」選取欄位，用於篩除在 FROM 子句中指定資源時無法使用的資源欄位、區隔欄位和指標欄位。

歸因資源

如果有已歸因的資源，這些歸因資源會以隱含形式與您在 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

注意： 如果 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") 之間使用，不能在單一運算子條件 (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 (遞減)。預設值為遞增。

此查詢範例按點擊次數遞減排序 (由高至低)：

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"

瞭解詳情

• 查詢文法