Ordering and limiting results

  • Use the ORDER BY clause to specify the order of rows in your response, optionally specifying ASC for ascending or DESC for descending order.

  • Ordering is subject to restrictions, including not being allowed for attributes of non-selected resources, non-selected metrics, non-selected segments, or for fields of certain types.

  • The LIMIT clause can be used to restrict the total number of results returned, which, when combined with ORDER BY, allows for the creation of "top N" reports.

  • Filtering has limitations, such as not being allowed on segments without selecting them (except for core date segments) or on fields or attributes of repeated fields of any message type except primitives.

The Google Ads Query Language lets you sort and cap the rows returned in your query responses using the ORDER BY and LIMIT clauses.

Order results

You can specify the order of rows in your response using the ORDER BY clause, which consists of one or more comma-separated sequences of:

FieldName (ASC | DESC)?

If you don't specify ASC or DESC after a field name, the Google Ads API defaults to ASC. If you omit the ORDER BY clause entirely, the order of returned rows is non-deterministic.

The following ORDER BY clause sorts a campaign-level report by descending impressions and ascending campaign name:

ORDER BY metrics.impressions DESC, campaign.name ASC
  • By attributes of non-selected resources
  • By non-selected metrics
  • By non-selected segments
  • For fields of the following types:
    • MESSAGE
    • Repeated fields
    • Attributes of repeated fields

Limit the number of results

You can limit the total number of results returned using the LIMIT clause with a positive integer (1 or greater; LIMIT 0 is not valid). Combining this with results ordering, you can produce "top N" reports, such as a report containing the five campaigns with the highest impressions over the last 30 days:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Filter results

When combining WHERE filters with ORDER BY and LIMIT, keep the following filtering restrictions in mind:

  • Filtering is not allowed on segments without selecting them, except for "core" date segment fields (segments.date, segments.week, segments.month, segments.quarter, and segments.year).
  • Filtering is not allowed on composite MESSAGE fields directly (except primitive wrapper messages such as Int64Value and StringValue); filter on their primitive scalar (int64, string, bool) or enum subfields instead.
  • Filtering is not allowed on composite MESSAGE attributes of repeated fields; only primitive scalar (int64, string, bool), enum, or primitive wrapper subfields can be filtered.
Previous
Case sensitivity