Google Ads

The AdWords Query Language (AWQL)  |  AdWords API  |  Google Developers

AWQL is a SQL-like language for performing queries against most common AdWords
API services. Any service with a query() method is supported.

AWQL is inspired by SQL, though it does not support the full SQL vocabulary.
Notable omissions are the JOIN and GROUP BY clauses.

For each service, you can get the list of queryable fields from
Selector Fields.

Additionally, you can use AWQL to query reports. See
Report Types for a comprehensive list of
queryable fields.

Using AWQL in service calls

AWQL is usually a more efficient way to code the same call.
For example, here’s a selector you might use for
CampaignService.get():


  Id
  Name
  
    Status
    EQUALS
    ENABLED
  
  
    Name
    ASCENDING
  
  
    0
    50
  

The equivalent AWQL query string for
CampaignService.query() is:

SELECT Id, Name
WHERE Status = 'ENABLED'
ORDER BY Name ASC
LIMIT 0,50

Our client libraries feature code samples using AWQL,
for example this complete code sample for getting campaigns with AWQL:

Notes

  • A FROM clause is not needed since the data source is already determined
    by the service to which the request is sent.
  • A DURING clause is not allowed in service calls, but is allowed in
    reporting calls. The time zone of the account
    is used.
  • Although keywords (for example, WHERE) are not case-sensitive, field
    (column) names (such as Name) and literals (such as ENABLED) are
    case-sensitive
    .
  • When using IN and NOT_IN operators in your WHERE clause, you are
    limited to 10,000 items.

Using AWQL with reports

AWQL is often used in reporting. Instead
of specifying the XML fragment in the “__rdxmlPOST parameter as you
normally would for reports, supply these two parameters:

  1. __rdquery“: contains the AWQL query string.
  2. __fmt“: defines the report download
    format
    .

Example (POST body):

__rdquery=SELECT+Criteria+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20150101,20150325&__fmt=CSV

There are also some usage differences when using AWQL for reports:

  • The query must contain a report
    type

    in the FROM clause, for example:

    SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT

    Note that while FROM is disallowed in service calls, it is mandatory in
    report downloads.

  • Date ranges for the report are defined in the DURING clause of the query.
    Date ranges can be specified in two different ways:

    1. A custom date range using regular AWQL syntax, for example:

      SELECT Id, Criteria, AdGroupName
      FROM KEYWORDS_PERFORMANCE_REPORT
      DURING 20190101,20190325
    2. A date range type, for example:

      SELECT Id, Criteria, AdGroupName
      FROM KEYWORDS_PERFORMANCE_REPORT
      DURING LAST_7_DAYS
  • To get data for all dates (the equivalent of ALL_TIME), you can omit the
    DURING clause from your query. However, this is only allowed if the
    SELECT clause of your query does not include the Date or Week column.

  • ORDER BY and LIMIT (sorting and paging) are NOT supported for
    reports. Including these clauses in a query will generate an error.

  • To omit zero-impression rows, include a WHERE Impressions > 0 condition.

Formal grammar

Here is the formal AWQL grammar for reference.

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause?3 LimitClause?4
SelectClause     -> SELECT ColumnList
FromClause       -> FROM SourceName
WhereClause      -> WHERE ConditionList
DuringClause     -> DURING DateRange
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT StartIndex , PageSize

ConditionList    -> Condition (AND Condition)*
Condition        -> ColumnName Operator Value
Value            -> ValueLiteral | String | ValueLiteralList | StringList
Ordering         -> ColumnName (DESC | ASC)?
DateRange        -> DateRangeLiteral | Date,Date
ColumnList       -> ColumnName (, ColumnName)*
ColumnName       -> Literal
SourceName       -> Literal
StartIndex       -> Non-negative integer
PageSize         -> Non-negative integer

Operator         -> = | != | > | >= |  StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]5
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> [ ValueLiteral (, ValueLiteral)* ]5
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | LAST_WEEK | LAST_BUSINESS_WEEK | THIS_MONTH |
                    LAST_MONTH | LAST_14_DAYS | LAST_30_DAYS | THIS_WEEK_SUN_TODAY |
                    THIS_WEEK_MON_TODAY | LAST_WEEK_SUN_SAT
Date             -> 8-digit integer: YYYYMMDD

Notes

  • 1FROM is disallowed in service calls but required in report
    downloads.
  • 2DURING is disallowed in service calls. It is required in
    report downloads if the SELECT clause of your request includes the Date
    or Week column.
  • 3ORDER BY is disallowed in report calls.
  • 4LIMIT is disallowed in report calls.
  • 5 For StringList and ValueLiteralList, square brackets [
    ]
    are required, elsewhere, they denote a range.
  • ? signifies optional; * signifies one or more.
  • Order: SELECTFROMWHEREDURINGORDER BYLIMIT
  • All keywords are case-insensitive.
  • Column names and Literals are case-sensitive.
  • White space doesn’t matter.
  • Both double quotes and single quotes are accepted for strings. Escape
    sequences are ", ', \.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close