Google Ads Query Language grammar

  • Google Ads Query Language queries consist of optional and required clauses such as SELECT, FROM, WHERE, ORDER BY, LIMIT, and PARAMETERS.

  • Various operators can be used in the WHERE clause for conditions, including comparison, containment, and pattern matching operators.

  • Field names, resource names, strings, numbers, and literals follow specific syntax rules defined by regular expressions.

  • Specific rules and limitations apply to the REGEXP_MATCH and LIKE operators.

This page contains the Google Ads Query Language grammar reference. For query structure details, see Query structure.

Grammar reference

Here is the Google Ads Query Language grammar reference (in regular expression notation):

Query            -> SelectClause FromClause? WhereClause? OrderByClause?
                    LimitClause? ParametersClause?
SelectClause     -> SELECT FieldName ("," FieldName)*
FromClause       -> FROM ResourceName
WhereClause      -> WHERE Condition (AND Condition)*
OrderByClause    -> ORDER BY Ordering ("," Ordering)*
LimitClause      -> LIMIT PositiveInteger
ParametersClause -> PARAMETERS Literal "=" Value ("," Literal "=" Value)*

Condition        -> FieldName IS NULL
                  | FieldName IS NOT NULL
                  | FieldName BETWEEN Value AND Value
                  | FieldName Operator Value
Operator         -> "=" | "!=" | ">" | ">=" | "<" | "<=" | IN | NOT IN
                  | LIKE | NOT LIKE | CONTAINS ANY | CONTAINS ALL
                  | CONTAINS NONE | DURING
                  | REGEXP_MATCH | NOT REGEXP_MATCH
Value            -> Literal | LiteralList | Number | NumberList | String
                  | StringList | Function
Ordering         -> FieldName (ASC | DESC)?

FieldName        -> [a-z]([a-zA-Z0-9._])*
ResourceName     -> [a-z]([a-zA-Z0-9_])*

StringList       -> "(" String ("," String)* ")"
LiteralList      -> "(" Literal ("," Literal)* ")"
NumberList       -> "(" Number ("," Number)* ")"

PositiveInteger  -> [1-9]([0-9])*
Number           -> -?[0-9]+(\.[0-9]+)?
String           -> ("'" SingleQuoteChar* "'") | ('"' DoubleQuoteChar* '"')
SingleQuoteChar  -> [^'\\\r\n] | EscapeSequence
DoubleQuoteChar  -> [^"\\\r\n] | EscapeSequence
EscapeSequence   -> "\\" ("\\" | "'" | '"' | "n" | "r" | "t")
Literal          -> [a-zA-Z]([a-zA-Z0-9_])*

Function         -> LAST_14_DAYS | LAST_30_DAYS | LAST_7_DAYS
                  | LAST_BUSINESS_WEEK | LAST_MONTH | LAST_WEEK_MON_SUN
                  | LAST_WEEK_SUN_SAT | THIS_MONTH | THIS_WEEK_MON_TODAY
                  | THIS_WEEK_SUN_TODAY | TODAY | YESTERDAY
  • ? indicates an optional element.
  • * means zero or more; + means one or more.
  • (...) indicates a grouping, while "(" and ")" indicate literal parentheses.
  • [a-z0-9] signifies character ranges, and [^...] signifies any character except the listed characters.
  • | stands for "or".

Rules and limitations

  • FromClause is required when querying GoogleAdsService and must be omitted when querying GoogleAdsFieldService.

  • WhereClause supports combining conditions only with AND. Logical OR is not supported; use the IN or REGEXP_MATCH operator instead.

  • The REGEXP_MATCH operator uses RE2 syntax.

  • To match a literal [, ], %, or _ using the LIKE operator, surround the character in square brackets. For example, the following condition matches all campaign.name values that start with [Earth_to_Mars]:

    campaign.name LIKE '[[]Earth[_]to[_]Mars[]]%'

  • The LIKE operator can only be used on a string field, not an array.

Previous
Overview
Next
Query structure