查询结构和子句

查询由多个子句组成： 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子句中指定资源时无法使用的资源字段、 细分字段和指标字段。

归因资源

如果有归因资源，它们会与您在 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.resource_name 将包含在响应中，因为选择了 campaign.id：

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 参数可让您排除 resource_name 字段，该字段属于 SELECT 子句中未明确请求的所有资源。默认值为 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 子句中包含的指标时要使用的币种。默认情况下，系统会使用 customer_id 指定的账号的币种。如果您设置此参数， 则需要使用 ISO 4217 3 个字符的货币代码。例如：USD、EUR。

以下示例查询以 customer_id 指定的账号的币种返回 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"

启用 MCC 扩展

如果将 enable_mcc_expansion 参数设置为 true，则可以为 FROM 子句中的资源添加以 customer_id 为根的所有账号中的指标、字段和细分。除非在 metrics_currency 参数中明确指定，否则响应将使用 customer_id 的币种。

注意： enable_mcc_expansion 参数仅与 bidding_strategy 兼容。API 会随着时间的推移添加更多资源。

以下示例查询从以 customer_id 为根的账号层次结构中的所有账号返回 bidding_strategy.name、bidding_strategy.type 和 metrics.cost_micros，因为 enable_mcc_expansion 参数设置为 true。

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

了解详情

• 查询语法