查詢結構和子句

查詢由多個子句組成：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 自訂變數

您可以使用 ID 在 SELECT 子句中加入 Floodlight 自訂變數。

在這個範例中，查詢包含了廣告活動資源的 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 子句中指定資源時無法使用的資源欄位、區隔欄位和指標欄位。

已歸因的資源

如果可用的屬性資源，會與您在 FROM 子句中指定的資源隱含地彙整。您只需將這些屬性加入 SELECT 子句，即可傳回其值。

這個範例查詢會傳回廣告群組 ID 和廣告活動 ID，因為 campaign 是 ad_group 資源的屬性資源。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

注意： 並非所有資源都有屬性資源。「Reference」部分會詳細說明每項資源可用的歸因資源。

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 個字元的貨幣代碼。例如：美元、歐元。

這個範例查詢會以帳戶的當地幣別傳回 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"

啟用「我的客戶中心」擴展功能

將 enable_mcc_expansion 參數設為 true 後，您就可以針對 FROM 子句中的資源，納入 login_customer_id 和下方所有服務帳戶的指標、欄位和區隔。除非在 metrics_currency 參數中明確指定，否則回應會使用 login_customer_id 的幣別。

注意： enable_mcc_expansion 參數僅與 bidding_strategy 相容。這個 API 日後會納入更多資源。

由於 enable_mcc_expansion 參數已設為 true，因此這個範例查詢會傳回 login_customer_id 和所有下方供應帳戶的 bidding_strategy.name、bidding_strategy.type 和 metrics.cost_micros。

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

瞭解詳情

• 查詢文法