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
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
<serviceSelector> <fields>Id</fields> <fields>Name</fields> <predicates> <field>Status</field> <operator>EQUALS</operator> <values>ENABLED</values> </predicates> <ordering> <field>Name</field> <sortOrder>ASCENDING</sortOrder> </ordering> <paging> <startIndex>0</startIndex> <numberResults>50</numberResults> </paging> </serviceSelector>
The equivalent AWQL query string for
SELECT Id, Name WHERE Status = 'ENABLED' ORDER BY Name DESC LIMIT 0,50
Our client libraries feature code samples using AWQL, for example this complete code sample for getting campaigns with AWQL:
FROMclause is not needed since the data source is already determined by the service to which the request is sent.
DURINGclause is not allowed in service calls, but is allowed in reporting calls.
- 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
NOT_INoperators in your
WHEREclause, 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 "
POST parameter as you
normally would for reports, supply these two parameters:
__rdquery": contains the AWQL query string.
__fmt": defines the report download format.
There are also some usage differences when using AWQL for reports:
The query must contain a report type in the
FROMclause, for example:
SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**
Note that while
FROMis disallowed in service calls, it is mandatory in report downloads.
Date ranges for the report are defined in the
DURINGclause of the query. Date ranges can be specified in two different ways:
A custom date range using regular AWQL syntax, for example:
SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING 20160101,20160325
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
DURINGclause from your query. However, this is only allowed if the
SELECTclause of your query does not include the
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 > 0condition.
Here is the formal AWQL grammar for reference.
Statement -> SelectClause FromClause1 WhereClause? DuringClause2 OrderByClause? LimitClause? 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 -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE | CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE | CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL String -> StringSingleQ | StringDoubleQ StringSingleQ -> '(char)' StringDoubleQ -> "(char)" StringList -> [ String (, String)* ] ValueLiteral -> [a-zA-Z0-9_.]* ValueLiteralList -> **[** ValueLiteral (, ValueLiteral)* **]**3 Literal -> [a-zA-Z0-9_]* DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK | LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH Date -> 8-digit integer: YYYYMMDD
FROMis disallowed in service calls but required in report downloads.
DURINGis optional in service calls. It is required in report downloads if the
SELECTclause of your request includes the
ValueLiteralList, square brackets [ ] are required, elsewhere, they denote a range.
*signifies one or more.
- 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