查询由多个子句组成: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
子句中指定的资源隐式联接。您只需将其属性添加到 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
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
如需详细了解如何细分报告,请参阅细分。
大小写区分
根据字符串值进行过滤时,每个运算符的默认大小写对于正确过滤结果都起着重要作用。
下表显示了每个运算符默认区分大小写。
默认区分大小写 | |
---|---|
=/!= |
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"