查询结构和子句

查询由多个子句组成：SELECT、FROM、WHERE、ORDER BY、LIMIT 和 PARAMETERS。

子句使用合并为单个查询请求的字段名称、资源名称、运算符、条件和排序。

简单来说，要构建查询，您需要：

• 指定从中检索数据的资源。
• 添加字段和指标以定义要返回的数据。
• 添加细分以对结果进行分组。
• 添加归因资源以隐式联接相关的资源数据。
• 过滤、排序和限制搜索结果范围。

SELECT 子句

SELECT 子句：

• 是查询中的 required 子句。
• 指定要在请求中提取的一组字段。
• 接受以逗号分隔的资源字段、自定义列、自定义 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.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 子句中包含的指标时要使用的货币。默认设置为帐号使用本地货币。如果您设置此参数，则需要使用由 3 个字符组成的 ISO 4217 货币代码。例如：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"

了解详情

• 查询语法