查询结构

提示： 使用交互式查询构建器构建和验证 Google Ads 查询语言查询。

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

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

子句使用字段名称、资源名称、运算符、条件和排序来帮助您选择正确的数据。合并为单个查询后，您可以将请求发送到 Google Ads API。

要点： GoogleAdsFieldService 为 Google Ads 查询语言客户端提供了一个目录，其中包含有关所有资源字段、细分字段和指标的元数据、它们之间的关系以及它们在每个子句中的可用性。由于可查询的资源、字段、细分和指标集因 API 主要版本而异，因此请在您要定位的 API 版本的端点查询 GoogleAdsFieldService。如需了解详情，请参阅 GoogleAdsField 和版本专属差异的相关文档。

条款

以下部分介绍了每个 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

注意： 由于以下限制，某些字段无法在 SELECT 子句中选择：

• 查询不可选择的字段。这些字段的 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

要点： 如果 FROM 子句中的资源将另一资源列为 segment，则选择该资源的任何属性都会起到细分的作用。

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 子句中使用其中至少一个细分。

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

要点： 分隔符 AND 只能在运算符条件之间使用 (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE')，而不能在单个运算符条件内使用 (WHERE segments.device != 'DESKTOP' AND 'MOBILE')。

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

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

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

要点： LIMIT 可让您截断结果。如需检索大型结果集而不截断，请使用 GoogleAdsService.SearchStream 流式传输行或使用 GoogleAdsService.Search 进行分页。

参数

借助 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。

注意： 如果您计划将任何返回的对象用于更新或移除操作，我们建议您将此选项设置为 false，因为没有资源名称的资源无法在 mutate 操作中使用。如果您将此选项设置为 true，请务必明确请求您使用查询提取的主要资源和任何归因资源的资源名称。

查询	返回的资源
SELECT campaign.name, customer.id FROM campaign	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	无 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	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'