AQL Predicates

 

Using predicates in your AQL query is entirely optional. You can filter the result set by any number of predicates or none at all. Each predicate expresses a condition that must be true in order for the service to include a record in the result set.

There is an implicit ‘AND’ between each predicate. If you repeat a predicate for a field, there is an implicit 'OR' between them.

Each predicate refers to a field in the schema of an audit trail type. If the field name does not specify an audit trail type, then the field must exist for all selected audit trail types. If the field name specifies an audit trail type specified with the "type:" parameter, then the predicate applies only to that audit trail type.

AQL predicate behavior examples

Example A: Type=wingui, shellui; user = “joe”

The above example selects all Windows and UNIX sessions for joe.

Example B: Type=wingui, shellui; shellui.user = “joe”

The above example selects all Windows sessions but only UNIX sessions for joe.

The service categorizes predicates according to the field data type:

  • String
  • Number
  • Boolean
  • Date / time
  • IP
  • Enumeration

AQL string predicate behavior

Here are some examples of how to filter an AQL query based on string predicates:

AQL query Filter behavior
field = "<string>",”<string2>”,… exact match
field != "<string>", “<string2>”,… not equals (exact match)
field = "<string>*", “<string2>*”,… starts with
field != "<string>*", “<string2>*”,… not starts with

AQL number predicate behavior

Here are some examples of how to filter an AQL query based on number predicates:

AQL query Filter behavior
field = <number> equals
field != <number> not equal
field >= <number> greater than or equal
field > <number> greater than

field <= <number>

smaller than or equal

field < <number>

smaller than

You can replace <number> with any integer or floating point number, such as 1 or -3.14.

AQL boolean predicate behavior

Here are some examples of how to filter an AQL query based on boolean predicates:

AQL query Filter behavior
field = true true
field != false> false

AQL Date and time predicate behavior

Here are some examples of how to filter an AQL query based on date and time predicates:

AQL query Filter behavior
field is (not) before <datetime> before a specific date and time or not
field is (not) after <datetime> after a specific date and time or not
field is (not) between <datetime> <datetime> between two dates and time or not
field is (not) in_past <number> <unit> in the past period of time or not, where the unit is day, hour, or minute

field is (not) in <predefined time>

field is not in the predefined time or not

Replace <datetime> with a particular date and time with the following format:

  • Y-M-D, for example 2019-12-15
  • Y-M-D h:m:s, for example 2019-12-15 15:30:00

Replace <predefined time> with any of the following values:

  • today
  • yesterday
  • this week
  • last week
  • this month
  • last month
  • this year
  • last year

AQL IP predicate behavior

Here are some examples of how to filter an AQL query based on IP address predicates:

AQL query Filter behavior
field = <ip> equals
field != <ip> not equal
field >= <ip> greater than or equal
field > <ip> greater than

field <= <ip>

smaller than or equal

field < <ip>

smaller than

AQL enumeration predicate behavior

Here are some examples of how to filter an AQL query based on enum predicates:

AQL query Filter behavior
field = <enum> equals
field != <enum> not equal

Replace <enum> with the values appropriate for the field you're querying against.

For example, filtering for a session state involves specifying an enum value:

state = Terminated
state != InProgress