The AdWords Query Language (AWQL)
原文:
https://developers.google.com/adwords/api/docs/guides/awql
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()
:
<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 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 asName
) and literals (such asENABLED
) are case-sensitive. - When using
IN
andNOT_IN
operators in yourWHERE
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 "__rdxml
" POST
parameter as you normally would for reports, supply these two parameters:
- "
__rdquery
": contains the AWQL query string. - "
__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:-
A custom date range using regular AWQL syntax, for example:
-
-
SELECT Id, Criteria, AdGroupName
FROM KEYWORDS_PERFORMANCE_REPORT
DURING 20190101,20190325 -
A date range type, for example:
-
SELECT Id, Criteria, AdGroupName
Note: The DateRangeTypes
FROM KEYWORDS_PERFORMANCE_REPORT
DURING LAST_7_DAYSALL_TIME
andCUSTOM_DATE
are not supported.
-
-
To get data for all dates (the equivalent of
ALL_TIME
), you can omit theDURING
clause from your query. However, this is only allowed if theSELECT
clause of your query does not include theDate
orWeek
column. -
ORDER BY
andLIMIT
(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 -> = | != | > | >= | < | <= | 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