Search Ads 360 Query Language

  • The 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.

  • You can utilize the SearchAds360Service to query resources, attributes, segments, and metrics, while the SearchAds360FieldService helps you retrieve metadata about available fields and resources.

  • Queries can be structured to retrieve attributes of resources, associated metrics, segments for specific timeframes, and related resource attributes.

  • Metadata about fields can be retrieved by querying the SearchAds360FieldService with the desired field name.

The Search Ads 360 Query Language allows you to build search queries to retrieve reporting data and resource metadata using the Search Ads 360 Reporting API.

Search services

You can use the Search Ads 360 Query Language to query the API using:

SearchAds360Service

Use this service to query resources and their related attributes, segments, and metrics. There are two methods, Search and SearchStream.

SearchAds360Service queries return a list of SearchAds360Row instances:

  • Each row represents a resource.
  • If requested, rows include attributes and metric fields.
  • If you request segments, additional rows are included for each segment-resource tuple.

See Create search reports for more information.

SearchAds360FieldService

Use this service to query for metadata about available fields and resources. The service provides a catalog of queryable fields with specifics about their compatibility and type.

SearchAds360FieldService returns a list of SearchAds360Field instances:

  • Each field contains details about the requested field.

See Retrieve resource metadata to learn more.

Basic query examples

The following sections provide basic query examples that you can adapt to build your own queries.

Query for attributes of a resource

This is a basic query for attributes of the campaign resource that returns the campaign ID, name, and status:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id
  • Each returned SearchAds360Row represents a campaign object.
  • Rows are populated with the selected fields (including the given campaign's resource_name).
  • The query orders by campaign ID.

See campaign for other available fields you can use in your queries.

Query for metrics

This is a basic query for metrics related to attributes of the campaign resource:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id
  • The query returns campaigns with the status PAUSED and more than 1000 impressions.
  • Each returned SearchAds360Row has a metrics field populated with the selected metrics.
  • The query orders by campaign ID.

See metrics for other available metrics you can use in your queries.

Query for segments

This is a basic query for segments related to attributes of the campaign resource:

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
  • The query returns campaigns with the status PAUSED and more than 1000 impressions.
  • It segments the data by date.
  • As a result of the segmentation, each SearchAds360Row represents a tuple of a campaign and the date segment.
  • The query orders by campaign ID.

See segments for a list of segments you can use in your queries and Segmentation for more information about segmenting your reports.

This is a basic query on the campaign resource that joins attributes of the bidding_strategy resource, if available. This type of related resource is known as an attributed resource.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id
  • The query selects campaign attributes and related attributes from each campaign selected.
  • Each returned SearchAds360Row represents a campaign object populated with the selected campaign attributes, as well as, the selected bidding strategy attribute, bidding_strategy.name.

See campaign to find out which attributed resources are available for campaign queries.

Query for field metadata

You can use SearchAds360FieldService to retrieve field metadata.

This is a basic query for field metadata:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = RESOURCE/FIELD
  • 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).

See Retrieve resource metadata for more information about retrieving field metadata.

Learn more

Learn more about how to build queries in the Search Ads 360 Reporting API: