Search Ads 360 查询语言
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
借助 Search Ads 360 查询语言,您可以构建搜索查询,以使用 Search Ads 360 Reporting API 检索报告数据和资源元数据。
搜索服务
您可以使用 Search Ads 360 查询语言通过以下方式查询 API:
SearchAds360Service
您可以使用此服务查询资源及其相关属性、细分和指标。有两种方法,即 Search
和 SearchStream
。
SearchAds360Service
查询会返回 SearchAds360Row
实例的列表:
- 每一行代表一个资源。
- 如果请求了,行将包含属性和指标字段。
- 如果您请求了片段,系统会为每个片段-资源元组添加其他行。
如需了解详情,请参阅创建搜索报告。
SearchAds360FieldService
您可以使用此服务查询有关可用字段和资源的元数据。
该服务提供了一个可查询字段的目录,其中包含有关其兼容性和类型的详细信息。
SearchAds360FieldService
会返回 SearchAds360Field
实例的列表:
如需了解详情,请参阅检索资源元数据。
基本查询示例
以下部分提供了基本的查询示例,您可以调整这些示例以构建自己的查询。
查询资源的属性
以下是针对 campaign
资源属性的基本查询,用于返回广告系列 ID、名称和状态:
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
ORDER BY campaign.id
- 返回的每个
SearchAds360Row
表示一个 campaign
对象。
- 系统会使用所选字段(包括给定广告系列的
resource_name
)填充行。
- 查询会按广告系列 ID 进行排序。
如需了解您可以在查询中使用的其他可用字段,请参阅 campaign
。
查询指标
以下是与 campaign
资源属性相关的指标的基本查询:
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
ORDER BY campaign.id
- 该查询会返回状态为
PAUSED
且展示次数超过 1000 的广告系列。
- 每个返回的
SearchAds360Row
都有一个 metrics
字段,其中填充了所选指标。
- 查询会按广告系列 ID 进行排序。
如需了解您可以在查询中使用的其他可用指标,请参阅 metrics
。
查询细分
以下是一个基本查询,用于查询与 campaign
资源的属性相关的细分:
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions,
segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
AND segments.date during LAST_30_DAYS
ORDER BY campaign.id
- 该查询会返回状态为
PAUSED
且展示次数超过 1000 的广告系列。
- 按日期细分数据。
- 经过细分后,每个
SearchAds360Row
都代表一个广告系列和日期细分的元组。
- 查询会按广告系列 ID 进行排序。
如需查看可在查询中使用的细分列表,请参阅 segments
;如需详细了解如何对报告进行细分,请参阅细分。
这是对 campaign
资源的基本查询,用于联接 bidding_strategy
资源的属性(如果有)。这种关联资源称为归因资源。
SELECT
campaign.id,
campaign.name,
campaign.status,
bidding_strategy.name
FROM campaign
ORDER BY campaign.id
- 该查询会从选定的每个广告系列中选择广告系列属性和相关属性。
- 每个返回的
SearchAds360Row
代表一个 campaign
对象,其中填充了所选的广告系列属性以及所选的出价策略属性 bidding_strategy.name
。
请参阅 campaign
,了解哪些归因资源可用于广告系列查询。
您可以使用 SearchAds360FieldService
检索字段元数据。
以下是针对字段元数据的基本查询:
SELECT
name,
category,
selectable,
filterable,
sortable,
selectable_with,
data_type,
is_repeated
WHERE name = RESOURCE/FIELD
- 将 RESOURCE OR FIELD 替换为资源(例如
customer
或 campaign
)或字段(例如 campaign.id
、metrics.impressions
或 ad_group.id
)。
如需详细了解如何检索字段元数据,请参阅检索资源元数据。
了解详情
详细了解如何在 Search Ads 360 Reporting API 中构建查询:
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[[["\u003cp\u003eThe Search Ads 360 Query Language enables you to construct search queries for retrieving reporting data and resource metadata via the Search Ads 360 Reporting API.\u003c/p\u003e\n"],["\u003cp\u003eYou can utilize the \u003ccode\u003eSearchAds360Service\u003c/code\u003e to query resources, attributes, segments, and metrics, while the \u003ccode\u003eSearchAds360FieldService\u003c/code\u003e helps you retrieve metadata about available fields and resources.\u003c/p\u003e\n"],["\u003cp\u003eQueries can be structured to retrieve attributes of resources, associated metrics, segments for specific timeframes, and related resource attributes.\u003c/p\u003e\n"],["\u003cp\u003eMetadata about fields can be retrieved by querying the \u003ccode\u003eSearchAds360FieldService\u003c/code\u003e with the desired field name.\u003c/p\u003e\n"]]],["The Search Ads 360 Query Language allows data retrieval via two services: `SearchAds360Service` and `SearchAds360FieldService`. The former fetches resource data using `Search` and `SearchStream` methods, returning rows with attributes, metrics, and segments. The latter retrieves metadata about available fields, detailing compatibility and type. Example queries demonstrate selecting attributes, metrics, segments, and related resource attributes. Metadata queries use `SearchAds360FieldService` to detail fields.\n"],null,["# Search Ads 360 Query Language\n\nThe Search Ads 360 Query Language allows you to build search queries to retrieve\nreporting data and resource metadata using the Search Ads 360 Reporting API.\n\nSearch services\n---------------\n\nYou can use the Search Ads 360 Query Language to query the API using:\n\n[`SearchAds360Service`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360service)\n\n: Use this service to query resources and their related attributes, segments,\n and metrics. There are two methods, *`Search`* and *`SearchStream`*.\n\n `SearchAds360Service` queries return a list of [`SearchAds360Row`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360row) instances:\n\n - Each row represents a resource.\n - If requested, rows include attributes and metric fields.\n - If you request segments, additional rows are included for each segment-resource tuple.\n\n See [Create search reports](/search-ads/reporting/concepts/search-reports) for\n more information.\n\n[`SearchAds360FieldService`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360fieldservice)\n\n: Use this service to query for metadata about available fields and resources.\n The service provides a catalog of queryable fields with specifics about their\n compatibility and type.\n\n `SearchAds360FieldService` returns a list of [`SearchAds360Field`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.resources#searchads360field)\n instances:\n\n - Each field contains details about the requested field.\n\n See [Retrieve resource metadata](/search-ads/reporting/concepts/resource-metadata) to learn more.\n\nBasic query examples\n--------------------\n\nThe following sections provide basic query examples that you can adapt to build\nyour own queries.\n\n### Query for attributes of a resource\n\nThis is a basic query for attributes of the `campaign` resource that returns\nthe campaign ID, name, and status: \n\n SELECT\n campaign.id,\n campaign.name,\n campaign.status\n FROM campaign\n ORDER BY campaign.id\n\n- Each returned `SearchAds360Row` represents a `campaign` object.\n- Rows are populated with the selected fields (including the given campaign's `resource_name`).\n- The query orders by campaign ID.\n\nSee [`campaign`](/search-ads/reporting/api/reference/fields/v0/campaign) for\nother available fields you can use in your queries.\n\n### Query for metrics\n\nThis is a basic query for metrics related to attributes of the `campaign`\nresource: \n\n SELECT\n campaign.id,\n campaign.name,\n campaign.status,\n metrics.impressions\n FROM campaign\n WHERE campaign.status = 'PAUSED'\n AND metrics.impressions \u003e 1000\n ORDER BY campaign.id\n\n- The query returns campaigns with the status `PAUSED` and more than 1000 impressions.\n- Each returned `SearchAds360Row` has a `metrics` field populated with the selected metrics.\n- The query orders by campaign ID.\n\nSee [`metrics`](/search-ads/reporting/api/reference/fields/v0/metrics) for other\navailable metrics you can use in your queries.\n\n### Query for segments\n\nThis is a basic query for segments related to attributes of the `campaign`\nresource: \n\n SELECT\n campaign.id,\n campaign.name,\n campaign.status,\n metrics.impressions,\n segments.date,\n FROM campaign\n WHERE campaign.status = 'PAUSED'\n AND metrics.impressions \u003e 1000\n AND segments.date during LAST_30_DAYS\n ORDER BY campaign.id\n\n- The query returns campaigns with the status `PAUSED` and more than 1000 impressions.\n- It segments the data by date.\n- As a result of the segmentation, each `SearchAds360Row` represents a tuple of a campaign and the date segment.\n- The query orders by campaign ID.\n\nSee [`segments`](/search-ads/reporting/api/reference/fields/v0/segments#segments.date) for a\nlist of segments you can use in your queries and [Segmentation](/search-ads/reporting/concepts/search-reports#segmentation) for more\ninformation about segmenting your reports.\n\n### Query for attributes of a related resource\n\nThis is a basic query on the `campaign` resource that joins attributes of the\n`bidding_strategy` resource, if available. This type of related resource is\nknown as an attributed resource. \n\n SELECT\n campaign.id,\n campaign.name,\n campaign.status,\n bidding_strategy.name\n FROM campaign\n ORDER BY campaign.id\n\n- The query selects campaign attributes and related attributes from each campaign selected.\n- Each returned `SearchAds360Row` represents a `campaign` object populated with the selected campaign attributes, as well as, the selected bidding strategy attribute, `bidding_strategy.name`.\n\nSee [`campaign`](/search-ads/reporting/api/reference/fields/v0/campaign#campaign.bidding_strategy_type)\nto find out which attributed resources are available for campaign queries.\n\n### Query for field metadata\n\nYou can use [`SearchAds360FieldService`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360fieldservice)\nto retrieve field metadata.\n\nThis is a basic query for field metadata: \n\n```sql\nSELECT\n name,\n category,\n selectable,\n filterable,\n sortable,\n selectable_with,\n data_type,\n is_repeated\nWHERE name = RESOURCE/FIELD\n```\n\n- Replace RESOURCE OR FIELD with either a resource (such as, `customer` or `campaign`) or a field (such as, `campaign.id`, `metrics.impressions`, or `ad_group.id`).\n\n| **Note:** These is no `FROM` clause in a query for field metadata.\n\nSee [Retrieve resource metadata](/search-ads/reporting/concepts/resource-metadata) for more information about retrieving field\nmetadata.\n\nLearn more\n----------\n\nLearn more about how to build queries in the Search Ads 360 Reporting API:\n\n- [Query structure and clauses](/search-ads/reporting/query/query-structure)\n- [Date ranges](/search-ads/reporting/query/date-ranges)\n- [Zero metrics](/search-ads/reporting/query/zero-metrics)\n- [Sample queries](/search-ads/reporting/query/sample-queries)\n- [Query grammar](/search-ads/reporting/query/query-grammar)"]]