查询结构

资源、细分和指标字段的查询可以发送到 GoogleAdsService Search 或 SearchStream 方法。如需使用 Google Ads 查询语言构建查询，您需要使用语言语法。如需大致了解 Google Ads 查询语言，请参阅 Google Ads 查询语言概览。查询由多个子句组成：

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

这些子句会使用字段名称、资源名称、运算符、条件和排序，帮您选出正确的数据。如果将这些数据合并到单个查询中，则可以使用 Google Ads API 发出请求。

条款

以下各部分介绍了每种 Google Ads 查询语言子句的用途和语法。

选择

SELECT 子句指定要在请求中提取的一组字段。SELECT 接受以英文逗号分隔的资源字段、细分字段和指标列表，并在响应中返回相应的值。查询中SELECT 子句是必需的。

以下示例查询展示了如何为给定资源选择属性：

SELECT
  campaign.id,
  campaign.name
FROM campaign

您可以在单个请求中请求不同的字段类型，例如：

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
  • 主要资源字段
    • campaign.id
    • campaign.name
  • 归因资源字段
    • bidding_strategy.id
    • bidding_strategy.name
  • 细分字段
    • segments.device
    • segments.date
  • 指标
    • metrics.impressions
    • metrics.clicks
  • 查询不可选择的字段。这些字段的 selectable 元数据属性将标记为 false。
  • 选择重复字段的属性。这些字段的 is_repeated 元数据属性将标记为 true。
  • 在 FROM 子句中选择给定资源不适用的字段。某些资源的属性无法同时选择，并且只有一部分指标和细分可用于 FROM 子句中的资源。
  • 选择彼此不兼容的细分或指标。如需详细了解这一点，请参阅细分部分。

有关上述条件的信息可在我们的参考文档或 GoogleAdsFieldService 中找到。

FROM

FROM 子句指定将返回的主要资源。FROM 子句中的资源定义了在给定查询的所有其他子句中可以使用哪些字段。FROM 子句中只能指定一个资源。在对 GoogleAdsService Search 或 SearchStream 方法的查询中，FROM 子句是必需的。不过，使用 GoogleAdsFieldService 时，FROM 子句应不指定。

虽然给定查询的 FROM 子句中只能存在一个资源，但归因资源中的字段也可能可用。这些资源会与 FROM 子句中的资源隐式联接，因此您只需将它们的属性添加到 SELECT 子句中即可返回它们的值。并非所有资源都具有提供方信息。在以下示例中，您可以同时从广告组请求广告组 ID 和广告系列 ID：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

系统始终会返回主要资源的 resource_name 字段。 在以下示例中，即使未在查询中明确选择 ad_group.resource_name，该指标也会包含在响应中：

SELECT ad_group.id
FROM ad_group

如果至少选择了一个字段，其他资源也会出现同样的情况。 例如，对于以下查询，回答中将包含 campaign.resource_name：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE 子句用于指定在过滤请求数据时要应用的条件。使用 WHERE 子句时，可以使用 AND 分隔符指定一个或多个条件。条件通常遵循 field_name Operator value 模式（或使用 BETWEEN value AND value、IS NULL 或 IS NOT NULL）。查询中的 WHERE 子句是可选的。

以下示例演示了如何使用 WHERE 返回指定时间段的指标：

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

您可以结合使用多个条件来过滤数据。此示例将请求过去 30 天内在移动设备上获得展示的所有广告系列的点击次数：

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

WHERE 子句中的细分必须位于 SELECT 子句中，但以下日期细分（称为核心日期细分）除外：

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

在以下查询中，请注意已选择 segments.date。 由于此细分受众群是核心日期细分受众群，因此需要在 WHERE 子句中提供由核心日期细分受众群组成的有限日期范围：

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

满足上述条件的所有细分是 segments.date、segments.week、segments.month、segments.quarter 和 segments.year。如果选择了这些细分，则必须在 WHERE 子句中使用其中至少一个细分。

如需详细了解日期过滤，请参阅日期范围。

过滤时，请务必注意运算符是否区分大小写。如需了解详情，请参阅区分大小写。

如需查看完整的运算符列表，请参阅语言语法。

ORDER BY

ORDER BY 子句用于指定返回结果的顺序。这样，您就可以根据字段名称按升序或降序排列数据。每个排序顺序都指定为 field_name，后跟 ASC 或 DESC。如果未指定 ASC 和 DESC，则默认顺序为 ASC。在查询中，ORDER BY 子句是可选的。

以下查询会按点击次数（从高到低）对返回的广告系列进行排序：

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

LIMIT

您可以使用 LIMIT 子句指定要返回的结果数。如果您只对摘要感兴趣，此功能会非常有用。

例如，LIMIT 可用于限制以下查询的结果总数：

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

参数

借助 PARAMETERS 子句，您可以为请求指定元参数。这些参数可能会影响返回的行类型。

支持以下元参数：

include_drafts

将 include_drafts 设置为 true，以允许返回草稿实体。 默认值为 false。

例如，以下查询会提取草稿广告系列以及常规广告系列：

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

将 omit_unselected_resource_names 设置为 true，以防止返回响应中每种资源类型的资源名称，除非在 SELECT 子句中明确请求。默认设置为 false。

omit_unselected_resource_names 示例
SELECT
  campaign.name,
  customer.id
FROM campaign
 		Returned resources:
campaign.resource_name
customer.resource_name
omit_unselected_resource_names 默认为 false，因此系统会返回所有 resource_name 字段。 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resources:
无。
omit_unselected_resource_names 被指定为 true，而 campaign.resource_name 和 customer.resource_name 不属于 SELECT 子句。 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resource:
campaign.resource_name
omit_unselected_resource_names 指定为 true，campaign.resource_name 作为 SELECT 子句的一部分进行请求。

其他语言规则

除了每个子句的示例之外，Google Ads 查询语言还具有以下可利用的行为：

  • 查询的主资源字段不需要在 SELECT 子句中。例如，您可能只想使用一个或多个主要资源字段来过滤数据：

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

  • 可以为给定资源专门选择指标；无需在查询中使用资源中的其他字段：

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • 可以选择细分字段，而不包含任何附带的资源字段或指标：

    SELECT segments.device FROM campaign

  • resource_name 字段（例如 campaign.resource_name）可用于过滤或排序数据：

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
上一页
查询语法
下一页
日期范围