IQL operators

The following operators are supported in IQL.

• Comparison operators

• Logical operators

• Exclude operators

• Pattern operators

• Units

• Supported units

• Fields with units

Comparison operators

Comparison operators are used to compare fields to values. The following comparison operators are supported by IQL.

Operator	Description	Example
=, ==	Equals	ip = 8.8.8.8
!=, <>	Does not equal	ip != 8.8.8.8
IN	Set/list operator - the field matches any of the listed values	ip IN (8.8.8.8, 8.8.4.4)
>	Greater than	ip_bytes > 100
<	Less than	ip_bytes < 100
>=	Greater than or equal to	ip_bytes >= 100
<=	Less than or equal to	ip_bytes <= 100

Most comparison operators are standard and intuitive. However, the IN operator has two behaviors worth mentioning:

• The values in the list must all be of the same type

• The values in the list will all be treated as exact matches

  • Fuzzy matches in lists are not supported

Also, the absence of a property can be tested by comparing the desired field to the null keyword.

// Returns HTTP requests that did not receive a response

http:status_code == null

Logical operators

Logical operators are used to chain clauses together to form a more complex query.

Operator	Description	Example
AND	Both clauses must be satisfied	ip = 8.8.8.8 AND port = 53
OR	Only one clause must be satisfied	ip = 8.8.8.8 OR port = 53
NOT	The inverse must be true (applied to other operators)	ip NOT IN (10.0.0.10, 8.8.8.8)

Logical operators allow chaining of multiple clauses. However, in the case of AND, all field comparisons must apply, which means all event-types involved must support all fields referenced. For example, the following query is illegal because flow events don't have a qtype_name field and dns events don't have a service field. In other words, no single event can have both a flow-specific field and a dns-specific field.

// invalid no single event can be both FLOW and DNS

dns:qtype_name = 'A' AND flow:service = 'dns'

The above example does not apply to the OR operator because a single event could be either a dns event or a flow event.

// This is ok, because a single event could match just one clause

dns:qtype_name = 'A' OR flow:service = 'dns'

Exclude operators

The exclude operator, for example, A exclude B, provides relative complement filtering that allows all items matching a criteria to be excluded from the result set.

For example, event_type = 'flow' and ip != 10.30.0.3 may return an event with src.ip = 10.30.0.1 and dst.ip = 10.30.0.3 because src.ip satisfies the constraint that the event has an ip field that is not 10.30.0.3. This may not be the desired intention. In comparison, event_type = 'flow' exclude ip = 10.30.0.3 would not return the event previously described. It will only return flow events excluding those events that match ip = 10.30.0.3.

Syntax:

The exclude operator is a low precedence, infix operator with left associativity. For example, with A, B, and X below representing complex expressions:

• A exclude X ## base example of matching everything in A except what matches X

• A and B exclude X ## this is the same as (A and B) exclude X

• A or B exclude X ## this is the same as (A or B) exclude X

• A exclude X and Y ## this is the same as A exclude (X and Y)

• A exclude X or Y ## this is the same as A exclude (X or Y)

• A exclude X exclude Y ## this is the same as (A exclude X) exclude Y which is the same as A exclude (X or Y)

• (A exclude X) and (B exclude Y) ## example of using exclude in a restricted context

• exclude X ## This is a special case and interpreted as * exclude X

Pattern operators

Pattern operators allow you to identify strings that contain certain patterns. The LIKE operator provides simple fuzzy matching, while the MATCHES operator provides access to Regex for more complex pattern matching.

Operator	Description	Example
LIKE	The LIKE operator supports simple pattern matching using % (any number of characters) and _ (a single character).	domain NOT LIKE "%.google.com"
MATCHES	Regex matching	domain MATCHES ".*\.(com|net|org|edu)"

Strings must be provided to pattern operators, meaning the characters must be surrounded by quotes. For the LIKE operator, the exact string will be matched if no wildcards exist in the provided string.

Units

IQL supports units for several numeric fields. Units are optional but can greatly increase readability of queries that use time, size, or distance values. Here are some examples:

dst.ip_bytes > 5MB  // will convert 5MB to 5242880 bytes

dst.ip_bytes > 5.5mb  // will convert 5.5mb to 5767168 bytes

Unit labels are case insensitive.

Supported units

Name	Type	IQL Label
bytes	size	b
kilobytes	size	kb
megabytes	size	mb
gigabytes	size	gb
terabytes	size	tb
petabytes	size	pb
miles	distance	mi
kilometers	distance	km
nanoseconds	time	ns
microseconds	time	us
miliseconds	time	ms
seconds	time	s
minutes	time	m
hours	time	h
days	time	d

Fields with units

Fields	Units
geo_distance	miles
lease_duration	seconds
ip_bytes	bytes
duration	seconds
total_ip_bytes	bytes
request_len	bytes
file.bytes	bytes