查询结构

**提示：** 使用互动式查询构建器 构建和验证 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 子句。

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

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

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