查询结构

可将针对资源、细分和指标字段的查询发送到 GoogleAdsService Search 或 SearchStream 方法。要使用 Google Ads 查询语言构建查询，您需要使用 语言语法。查询由一系列 子句：

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

这些子句会使用字段名称、资源名称、运算符、条件和排序，帮您选出正确的数据。一旦合并为 就可以使用 Google Ads API 来提出请求。

条款

视频：GAQL 字段兼容性

选择

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。
  • 选择重复字段的属性。这些字段将 isRepeated 个元数据属性已标记为 true。
  • 选择不适用于 FROM 中的指定资源的字段 子句。有些资源的属性不能同时选择，也不能同时选择 部分指标和细分将可用于 FROM 子句。
  • 选择互不兼容的细分或指标。对于 请参阅 细分部分。

有关上述情况的信息，请参阅我们的参考文档 或GoogleAdsFieldService起。

FROM

FROM 子句指定要返回的主要资源。通过 FROM 子句中的资源定义了哪些字段可用于 子句。在 FROM 子句。在查询语句中必须使用 FROM 子句 GoogleAdsService Search 或 SearchStream 方法，但在使用 GoogleAdsFieldService。

虽然给定查询的 FROM 子句中只能存在 1 项资源，但字段 “归因资源”中可能也可用这些资源包括 与 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。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。

allow_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'
上一页
查询语法
下一页
日期范围