Query filters

Use the query filter specs below in API requests that provide filtering capabilities. The filter string must be specified as an expression or list of expressions.

Simple expressions

Filters must be specified using the following grammar:

An expression has the general form:

<expr>

::=

<field> <operator> <value>

• <field> is a string. When <field> contains a space or a colon must be enclosed by double quotes.
• <operator> could be equality or relational operators, and follows specification as below:
  The equality operator "=" is defined only for string fields.
  The prefix match operator ":" is defined only for string fields.
  The relational operators "<" | ">" | "<=" | ">=" are defined only for timestamp fields.
  
• The <value> supplied should be string that may be in Timestamp format depending on the <field>. When <value> contains a space or a colon it must be enclosed in double quotes.

Expression lists

Expressions may be joined to form a more complex query. The BNF specification is:

<exprList>	::=	<expr> | <exprList> <conjunction> <expr> | <negation> <expr>
<conjunction>	::=	"AND" | "OR" | ""
<negation>	::=	"NOT"

Using the empty string as a conjunction acts as an implicit AND.
The precedence of joining operations, from highest to lowest, is NOT, AND, OR.

Examples

Given below are some example filters. Note that the actual fields supported may vary between the different versions of the API. For filter columns available in v1beta1 see here.

To query for all alerts created on or after April 5, 2018:
createTime >= "2018-04-05T00:00:00Z"

To query for all alerts from the source "Gmail phishing":
source="Gmail phishing"

To query for all alerts from a source which starts with "Gmail":
source:"Gmail"

To query for all alerts which started in 2017:
startTime >= "2017-01-01T00:00:00Z" AND startTime < "2018-01-01T00:00:00Z"

To query for all user reported phishing alerts from the source "Gmail phishing":
type="User reported phishing" source="Gmail phishing"