查询结构和子句

一个查询由许多子句组成，包括：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 子句中添加自定义 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

注意： 并非所有资源都有归因资源。参考部分包含每个资源可用的归因资源的详细信息。

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"

了解详情

• 查询语法